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About 
This Book 



The Advanced Programmer's Guide is intaided for progranmiers who are 
ejqjerienced with Prime 50 Series systems, have read the Prime User's 
Guide {DOC4130-4IA) and Programmer's Guide to BIND and EPFs 
(DOC8691-1IA) , are familiar with the Subroutines Reference Guide 
(DOC3621-190) and its first update package {UPD3621-31A) , are 
ejqjerienced in at least one hi^-level language supplied ty Prime 
(preferably PLl/G or FTN) , and have an understanding of the 
architecture of Prime systems as described in the Prime 50 Series 
Technical Summary {DOC6904-191) and in the System Ardiitecture Guide » 

Has guide consists of four volumes, and describes: 

• Executable Program Formats (EPFs) in Volume I of this series 

• The HlI^DS File System in Volume II of this series 

• The IRIM3S Ccjmmand Environment in Volume III of this series 

• New features for readers of this guide in Volume of this 
series 

• Standard error codes used ty ERIM3S, along with their messages 
and meanings, in Volume of this series 

Volume also contains information applicable to all of the other 
volumes, sudi as an ej^lanation of the presentation of the subroutine 
calls, general coding guidelines, and the like. 

Designed for systems-level programmers, this guide describes the 
lowest-level interfaces supported by HRI^DS and its utilities. 



IX 



Hi^er-level interfaces not described in this guide include: 

• Language-directed I/O 

• Ohe applications library (APELIB) 

• The sort packages (VSRELI and MSORTS) 

• Data management packages (such as MPLUSIB and PRISAMLIB) 

• Other subroutine packages 

All of these hicfier-level interfaces are described in other manuals, 
such as language reference manuals, and the Subroutines Reference 
Guide . 

This guide documents the low-level interfaces for use ty programmers 
and engineers who are designing new products such as language 
compilers, data managanent software, electronic mail subsystems, 
utility packages, and so on. Such products are tiiemselves hi^er-level 
interfaces, typically used fcy other products rather than by end users, 
and therefore must use some or all of the low^level interfaces 
described in this guide for best results. 

Because of the technical content of the subjects presented in this 
guide, it is e^^cted that this guide will be regularly used only by 
project leaders, design engineers, and tedmical supervisors rather 
than hy all progrannners on a project. Most of the information in this 
guide deals with interfaces to HRIMDS that are typically used only in 
small portions of a product, and with overall product design issues 
that should be considered before coding begins. Once the product is 
designed and the PRIfDS interfaces are designed and coded, a typical 
product can then be written fcy progrannmers whose knowledge of these 
issues is minimal. Of course, this statenent is predicated on the 
assumption that progrenmErs empLcy widely accepted programming 
practices such as modular, or structured, programming; functional and 
design specifications; and thorou^ unit debugging and testing. 



FRirC D0QJME3OTATIDN OONVEMTIDNS 

The following oonvoitions are used in command formats, statement 
formats, and in examples throughout this document. Examples illustrate 
the uses of these commands and statements in typical applications. 
Terminal input may be entered in either uppercase or lowercase letters. 



Convention 



UPIERCaSE 



lowercase 



Abbreviations 



underlining 

in 
examples 



Brackets 
[ ] 



Braces 

{ } 



Ellipsis 



Parentheses 
( ) 



Hyphen 



Explanation 

In oomnand formats, words 
in uppercase indicate the 
actual names of commands, 
statements, and keywords. 
Biese can be entered in 
either uppercase or 
lowercase letters. 

In command formats, words 
in Icwercase letters indicate 
items for which the user must 
substitute a suitable value. 

If a command or statanent 
has an abbreviation, it is 
indicated by underlining. 
In cases where the command 
or directive itself 
contains an underscore, the 
attoreviation is shown belcw 
the full name, and the name 
and abbreviation are placed 
within braces. 

In examples, user input 
is underlined but systati 
prompts and output are not. 



Brackets enclose one or 
more optional items. 
Choose none, one, or 
more of these items. 

Braces enclose a list 
of items. Choose one 
and only one of these 
items. 

An ellipsis indicates that 
the preceding item may be 
repeated. 

In oomraand or statement 
formats, parentheses must 
be entered exactly 
as shewn. 

Wherever a l^phen appears 
as the first letter of an 
option, it is a required 
part of that option. 



Example 
SLIST 



LOGIN user-id 



LOGOUT 



SETUQUOTA 
SQ 



OK, RESUME m_MCG 
TJiis is the output 
of m_MCG,CPL 
OK, 



r -LIST 1 
L -CANCEL J 



CLOSE I filename 
I ALL 



item-x [ , item-y] . . . 



DIM array (row, col) 



shxXj -list 



XI 
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Introduction to 
BIND and EPFs 



Ihis volume introduces EPFs (Executable Program Formats) and BIND, the 
new utility that creates them. It describes how to create EPFs and 
covers, in detail, concepts that apply to all EPFs and information 
applicable to two specific types of EPFs, program EPFs and library 
EPFs. 

Specifically, Volume I of this guide: 

• Explains what an EPF is 

• Compares EPFs to the previously available method of building 
programs under PRIMDS 

• Explains the dynamic linking mechanism 

• Describes the EPF mechanism 

• E)q>lains restrictions on the use of static-mode programs and on 
the use of static-mode libraries 

• Lists information and subroutines involving static information 
that should not be used in EPFs 

• Describes the effect EPFs may have on existing static-mode 
shared applications 
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It is important that you read all of Qiapters 1 throu^ 6 to understand 
how EPFs affect all aspects of prograrraning on Prime systems from 
Rev. 19.4 cai. Even if your installation does not intend to use EPFs, 
you should be aware of the effect EPFs may have on existing shared 
applications used at your installation; this topic is covered in 
Chapter 4. 

Prior to Rev. 19.4, SEG and LOAD were the only two utilities provided 
by Prime that linked programs. As of Rev. 19.4, a new linking utility 
named BIND is provided that creates programs using a new program 
format, the EPF. Chapter 1 introduces you to BIND and EPFs and 
compares the programming enviroiment provided by BIND and EPFs to the 
environments provided by the SEG and LQftD utilities. 

Other chapters in Volume I explain BIND and EPF concepts in greater 
detail: 

• Chapter 2 explains the dynamic linking mechanism, which allcws a 
program to call a subroutine that is not linked in with the 
program. 

• Oiapter 3 explains the EPF mechanism in detail, including 
elements of tiie Prime 50 Series architecture that relate 
directly to EPFs. 

• Chapter 4 ej^lains the effects that the advent of EPFs have on 
existing static-mode applications, even in an installation that 
does not switch over to using EPFs, 

• Chapters 5 and 6 describe the ways in which program EPFs and the 
two classes of library EPFs (program-class and process-class) 
are created, and the operational characteristics of each. 

• The rennaining chapters introduce some coding guidelines that you 
should adhere to when prograrraning EPFs, the concept of shared 
common data blocks and how to define them, and the use of 
linkage maps and the binary editor. 



WHAT IS AN EPF? 

An EPF is an executable file system object. You, the programmer, 
generate an EPF using BIND. An EPF may be used by a user or by another 
program. A file containing an EPF has a suffix of either .HJN or .KPn, 
where n is a digit (0-9) , The .HJN suffix indicates that the file 
contains the latest version of the EPF. The ,RRi suffix, if present, 
indicates an older version of the EPF; an old version of an EPF is 
kept only if at least one user is still using the EPF when the new 
version is installed. 
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Types of EPFs 

There are two types of EPFs: 

• Program EPFs, which contain a program having one entrypoint and 
which are invoked by explicitly running the program 

• Library EPFs, which contain subroutines having one or more 
entrypoints and which are invoked ty another program iirplicitly 
ty referencing an entrypoint within the library EPF 

Program EPFs : A program EPF contains a main entrypoint and related 
subroutinas that together constitute a single program. A program EPF 
is invoked ej^licitly by issuing the PRIMDS command RESU^E, ty calling 
a subroutine to invoke a program EPF, or by issuing a command that 
names a program EPF residing in UFD CMDNCO. 

TO a programmer, a program EPF is a file containing a program. To a 
user, a program EPF is either a HlI^DS command (if the EPF resides in 
UFD CMDNCO) or a program invoked via the RESUME command. To a program, 
a program EPF is a subroutine, having a standard calling sequence, that 
may be invoked by calling one of several miVOS subroutines. 

Chapter 5 contains detailed information about program EPFs (as distinct 
from library EPFs) . 

Library EPFs ; A library EPF contains many subroutines, some (or all) 
of whidh are entrypoints to that library EPF. A library EPF is not 
invoked explicitly as is a program EPF; instead, tiie pathname of the 
library EPF is placed in an entrypoint search list (ENTRY$.SR) by the 
System Administrator (for the default system-wide search list 
SYSTM>ENTRY$.SR) or by a user (for a private search list) . 

The dynamic linking mechanism, described later in this chapter, 
connects a library EPF to any program or subroutine that calls an 
entrypoint inside the library EPF, When any program or library calls a 
subroutine that is not contained within the program, it makes the call 
through a faulted Indirect Pointer (IP) , also known as a dynamic link. 
Upon recognizing the faulted IP, the dynamic linking mechaniam in 
PRIIOS takes action. First, it searches its own list of internal 
entrypoints (internal to PRIMDS) . Next, it scans the user's entrypoint 
search rules for library EPFs (or the special -STATICJOraLLIBRARIES 
object) , looking for a library that contains the subroutine named by 
the faulted IP as an entrypoint. 

If the faulted IP identifies, as its target, the name of one of the 
entrypoints in a library EPF, miNDS connects the library EPF to the 
program invoking the subroutine via the faulted IP, allowing the 
program to call any of the entrypoints in that library EPF. As further 
faulted IPs are encountered, HIIMDS converts those that identify 
, subroutines in that library EPF to point to the actual memory addresses 
of Entry Control Blocks (ECBs) in that library EPF. (An E^ is the 
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actual target of a subroutine call instruction, as it contains 
information on the subroutine such as where it is located, how much 
stack space it needs, and where its linkage information is located.) 
Subsequent uses of the affected IPs do not cause invocation of the 
(^namic linking mechanian; hence, they execute much faster. In fact, 
subsequent uses of such converted IPs execute as fast as IPs that were 
not faulted in the first place, such as IPs to statically allocated 
storage or to storage within the same program containing the IPs. 

To a programmer, a library EPF is a collection of related subroutines 
that are useful to more than one application. To a user, a library EPF 
is nothing more than an entry in the entrypoint search list, with whidi 
many users do not even concern themselves. To a program, a library EPF 
appears as a collection of entrypoints to which the program may link 
itself hy calling them via dynamic links (faulted IPs) . However, a 
program is not concerned with how entrypoints are distributed among 
library EPFs; the programmer who builds a library EPF must concern 
himself or herself with the optimal grouping of related entrypoints in 
one or more library EPFs. 

Qiapter 6 contains detailed information about library EPFs (as distinct 
from program EPFs) . 



WHY EPFS? 

EPFs are provided as an alternative to static-mode programs, which, 
until Rev, 19.4, were the only kind of progran supported by FRI^DS, 
Static-mode programs are created by the SEG and LOAD linking loaders, 
while EPFs are created only by the new (at Rev, 19,4) BIND linker. 

This section explains the history behind static-mode programs and EPFs, 
explains the disadvantages of static-mode programs, and explains the 
advantages of EPFs. During this discussion, information is presented 
suggesting hew botii static-mode programs and EPFs work. 



History of Linking Loaders Under PRIM3S 

Prior to Rev. 19.4, miVDS provided two linking loaders: 

• SEG, for linking and loading V-mode and I-mode programs 

• LOAD, for linking and loading R-mode programs 

These linking loaders are fully described in the SEG and LOAD Reference 
Guide , 

R-mode programs are limited to 128KB of memory in size, R mode is 
provided for compatibility so that programs writtai to run on the older 
Prime 100, 200, and 300 systems can run on newer Prime systems without 
modification. Such programs cannot take advantage of the large 
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segmented memory address space provided by IRIMDS starting with the 
Prime 400 system. (There are two submodes of R mode, 32R mode and 64R 
mode. Tlhe!/ differ only in their ability to reference memory.) 

V-mode and I-mode programs can take full advantage of the large 
segmented memory address space provided by IRIM3S. V-mode and I-mode 
differ only in the way instructions are decoded and in the fact that 
registers in I mode are organized around a general-purpose register set 
architecture, while V-mode registers retain the special-purpose 
register set architecture inherited from the predecessor of V mode, 
v^ich is R mode, (The predecessor of R mode is an almost entirely 
obsolete mode called s mode, which is used only during the very 
earliest phase of system boot and in certain system test and 
maintenance utilities, S mode consists of two submodes, 16 S mode and 
32S mode, whidi, like their counterparts in R mode, differ only in 
their ability to reference memory,) 



Single-Segnnent Limit and EgLSEG Requirement ; 
links and loads V-mode and I-mode 



R-Mode 



Although SEIG 
programs, pre-Rev. 19,4 IRIMDS 
provided no direct way to execute V-mode or I-mode programs; only the 
R-mode (or S-mode) program format was supported. The Rr-mode program 



format produces a static-mode program , 
of a static-mode program: 



There are five characteristics 



It is represented in a SAM (Sequential Access Method) file that 
consists sinply of a representation of the oontoits of a portion 
of segment '4000 when it contains the program. Nine hal&/ords 
of control inf carnation are followed fcy the memory image itself; 
the beginning and ending addresses of the memory image are in 
the nine halfwords of control information, as is the starting 
address of the program and the initial state of certain special 
R-mode registers, NO distinction is made in the static-mode 
image between procedure code, data, and uninitialized memory. 



Control Info (RVEC) 



Procedure Code 

Data 

Uninitialized IVIemory 
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It is always loaded into user segnent '4000 by miMDS; 
therefore, if static-mode program A is first loaded, followed ty 
static-mode program B, it is likely that loading program B will 
overwrite part or all of program A in memory unless they occujy 
completely separate areas in segment 4000. The default method 
of loading static-mode programs, however, starts all programs at 
location '1000 in segnent '4000; therefore, static-mode 
programs loaded using the default method will invariably 
overwrite each other. 



Segment '4000 




Segment '4000 




It is executed by IRIMDS when the user issues the RESUfG oomrrand 
identifying the static-mode program file, v*iich typically has 
the suffix .SAVE to identify it as a static-mode progran. 
FRIMDS loads the program into segnent '4000 and performs a 
nonlocal goto to the starting address of the progran; the 
program is not treated as a subroutine by rRI^DS. 



JMP 




PRIMOS) 



Segment '4000 
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It terminates execaition fcy calling one of several IRIIDS 
subroutines that return the user to PRIMDS ooiranand level, rather 
than by executing a return as a called subroutine mi^t do. 



Segment '4000 





CALL / 




"y 









PRIMOS) 



• It can use more than one segnent by directly referencing 
segments other than segonent '4000. However, ERIM3S does not 
manage these additioml segnents. If a progrsm uses five 
segments, then five segments remain allocated to the user when 
the program finishes. 

In order to free any segments referenced ty an R-mode program 
(but no longer in use because the program has terminated), the 
user must issue appropriate IXLSEG commands to delete the 
segments. (The EELSBG command is described in the IRI^DS 
Commands Reference Guide .) The additional segnents are also 
released when the user logs out. 

Due to the design of static-mode programs, one static-mode program 
cannot call another static-mode program as if it were a subroutine; 
the first static-mode program must give up control to the second 
program entirely, because the second program will destroy part or all 
of the first program. 

SBG — R-^^ode to Initialize V-Mode or I-Mode ; Because the static-mode 
mechanism does not handle V-mode or I-mode programs, the SBG loader is 
designed not only to provide the mechanism to link a V-mode or I-mode 
program, but also to enable the user to execute the program fcy typing: 

SEG program-name 

Ihe SBG program itself is a static-mode program that loads program-name 
into memory (into segments other than segnent '4000, which is where SBG 
resides) . Then, SBG sets up the V-mode/I-mode enviroiment and begins 
execution of tiie program. 

■ If a V-mode or I-mode program fits within a single segment, SBG can 
generate a static-mode image of the program in segnent '4000 that can 
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then be invoked directly using the RESUffil ooitmrand. However, the 
procedure for building such a program via SEG is complicated and 
definitely not intuitive. 



SEG for Shared Procedure Segnents ; If a V-mode or I-mode program is 
larger than a segment, but Its inpire data fits within a single 
segment, the program can be shared via SBG. SEG can generate, in 
segment '4000, a static-mode image of the impure portion of the 
program, which includes an interlude to the pure portion of the 
program; it can also generate static-mode images of the pure portions 
of the program in shared system-wide segnnents (for example, segments 
2030, 2031, 2032, and so on) . The procedure for building a shared 
program via SBG is extremely complex and has the following 
requirements ; 

The System Acininistrator must coordinate the use of *ared 
segnents on the systan and must assign shared segnent numbers to 
Droarams that arp +-n hp»nr>TtMi c^f^re^ r>rr>riramc 



oc^uciiub uii uie byiacan ana muse assign snare 
programs that are to become shared programs. 



• At every system ooldstart, the shared static-mode segnent images 
must be loaded into their corresponding shared segnents. 

• At system ooldstart, the shared segnents must be protected 
against modification. 

• The user must RESU^E the image of segnent '4000 generated by SEG 
to run the program. 

• To install a new version of the program reliably, the systan 
must be shut down and restarted. Otherwise, the possibility 
exists that a user may be executing the old version of the 
program when the new version is installed. This usually results 
in unrecoverable errors for that user. 

In addition, once a program is shared in syston-wide segnents, any user 
can examine or make copies of the pure code, even if that user cannot 
access the program itself (which is the impure and startup code 
residing in the image of segnent '4000). 

(See the SEG and LOAD Reference Guide for complete information on SEG 
and LOAD.) 



BIND, the New Linker 

As of Rev. 19.4, FRIMDS supports a new program type, called an EPF (for 
Executable Program Format) . To build EPFs, IRIMDS provides a new 
linker named BIND. BIND is not a loader, because it does not load the 
final linked program into memory; FRI^DS is solely responsible for 
loading an EPF into memory. 
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BIND, like SBG, can be used to create only V-ito6e and I-inode programs, 
frequently referred to as 64V-node or 321-inode programs. 

Using the BIND linker to create EPFs provides the follcwing benefits: 

• The BIND linker is much simpler to use than SEG, and is even 
siirpler than LOAD (while providing more capabilities) . iMs 
siitplicity is maintained even when large programs are linked via 
BIND, because BIND and PRIMDS manage very small and very large 
programs in the same way. 

• BIND allows external names (subroutine and common area names) to 
be a maximum of 32 characters in length; SBG limits external 
names to 8 characters, and LOAD to 6 characters, both by 
truncating external names. 

• Two distinct types of EPFs are provided, one type to contain 
programs (invoked directly by a user) and another type to 
contain subroutine libraries (invoked inplicitly by any program 
that references a subroutine in a library) . With SBG, building 
a library is difficult, and its invocation must be e35)licitly 
performed ty any program that wishes to invoke it by using an 
unusual program load sequence, 

• Program EPFs are directly invoked using the RESUME command, 
rather than ty an intermediate progran (as is sometimes 
necessary with the SBG loader) , 

• A program EPF may be debugged by EBG without having to use a 
different build sequence than that used to build the production 
version of the same program EPF. 

• Library EPFs are implicitly invoked when a program calls a 
subroutine in a library EPF; neither the library nor any 
subroutine in it needs to be made physically part of a program 
that uses the library, 

• Any user may create his or her own personal library EPF and use 
that library EPF fcy placing its pathname in the user's 
entrypoint search list (a list of libraries to search for 
subroutine entrypoints) , 

• A program EPF is invoked by ERIKDS as a subroutine, and may 
return to FRI^DS as a subroutine, 

• FRIICS separates memory used for EPFs, called dynamic manory , 
from memory used for static-mode programs, called static manory . 
Static memory for a user begins in segment '4000 and extoids 
upward for the number of static segments allocated for the user 
by EDITLEROFILE. Dynamic memory for a user begins at or beyond 
where static memory ends. Segnnents between the last static 
segment and the first dynamic segment for a user are not 
accessible. 
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Static-mode programs cannot acquire additional dynamic manory in 
the same w^ they acquire additional static memory (by simply 
referencing it) ; therefore, EPFs are guaranteed not to be 
corrupted by loading static-mode programs. 

While EPFs can use static memory, their use of static memory 
must be managed ty the prograraner; PRIM3S cannot keep track of 
which programs are using static memory as it can for dynamic 
memory. 

Most memory allocation is handled entirely by BIND, at program 
or library linking time, or by JRIMDS, at program or library 
invocation time. Memory allocation performed by BIND is done 
entirely within segments, v*ile miMDS performs the task of 
finding available segnents for the program. So that this may 
work, BIND generally does not put actual memory addresses into 
an EPF; it uses imaginary addresses , whidi identify locations 
within the EPF. FRIMDS translates these imaginary addresses 
into actual addresses once it knows where, in memory, it will 
place the EPF. As a result, a particular EPF can execute 
properly in segment '4354 at one point in time, and can later 
execute properly in segnient '4362, without needing to be 
relinked. 
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Because memory allocation is handled ty primds at runtime, 
ERIMDS ensures that EPFs do not overlay each other's memory 
space; this allows mai^ EPFs to be kept in memory at one time 
without resulting in the destruction of data among the EPFs, 
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An EPF separates procedure code that is pure (meaning it is not 
modified during program execution) , from linkage text, impure 
code, and common areas, which are not pure. IRIWDS uses this 
separation to protect segnents containing pure procedure code 
against modification by even the program itself, improving the 
chances of preventing a programming bug from turning into a 
disaster. A segnent is used either to contain the procedure 
code of, at most, caie EPF, or to contain the linkage text and 
ccxnmon areas for many EPFs. A procedure segonent may contain 
either pure or impure code, but only segnents containing pure 
code are shared and protected against writing. 
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ERIMDS also uses the separation of pure and iitpure code to 
automatically share pure code from a particular EPF between each 
user on a system that is using that EPF. 
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• rRIMDS Shares the pure code of an EPF in the per-user (private) 
memory of each user who is using that particular EPF. 
•flieref ore, other users cannot access this i^ared code unless 
they, too, invoke the EPF (implying that they have sufficient 
access to do this) . 
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Because BIND produces only imaginary addresses to point to 
locations within an EPF, FRIMDS, when it ^ares an EPF among two 
or more users, can use differait segment numbers for each user 
while still sharing the pure procedure code. For example, an 
EPF mi^t reside in segments '4352 and '4357 for user A, vrtiile 
also residing in segments '4363 and '4366 for user B. In this 
case, segnent '4352 for user A and segnent '4363 for user B 
could correspond to a single copy of the pure procedure code for 
that EPF; one copy of pure procedure code is therefore kncwn by 
two differait segment numbers for two users. 
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• ERIMDS further uses the separation of pure and iirpure code to 
avoid treating segments containing pure code as traditional 
virtual memory segments whose contents must be written out to 
the paging disk during paging. Instead, IRI^DS can always be 
sure of reading pure EPF segnents f ran a single copy of the EPF, 
since pure segments are "locked" against modification, and hence 
always up-to-date. This iirproves performance and uses less 
paging disk space. 
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Although PRIMDS autanatically shares EPFs between users, new 
versions of EPFs can be installed at any time by using the COPY 
oonmand to replace an old version. If the old version is still 
in use by at least one user, HlItDS keeps the old version on the 
disk, renaming it so that subsequent invocations of the EPF 
invoke the new version. A maximum of 10 old versions of an EPF 
may be kept in this fashion. Although ERIM3S creates the old 
versions, it is up to the owner of the EPF to delete them when 
they are no longer in use. 
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• An EPF can be ronoved from memory by issuing the REMDVE_EPF 
command. All memory associated with the removed EPF that 
belongs to the user issuing the command is thereby returned to 
the free memory pool. If no other users are using the EPF, this 
means that one or more segments, which contained the procedure 
code for the EPF, are returned to the system-wide free segnent 
pool. 

• The command line arguments used to invoke a program EPF can be 
received by that EPF as an argument to the main entrypoint of 
the EPF, due to the symmetric call/return flew of program EPF 
invocation by the HIIMDS command environment. Such a program 
need not make a special subroutine call to acquire the command 
line frcan the command environment. This feature prevents the 
side effect of wiping out any unparsed data on the original 
command line fcy aborting a running program and then typing 
STMT; sudi side effects can occur with programs that continue 
to use RnrK$$ to retrieve the command line token by token. 

• Users can write their own CPL functions by building program EPFs 
that interface with the command processor. 

• A program EPF can be executed by another program and treated as 
a command (vrtiich does not return a valite) or as a CPL function 
(which returns a string value) . 



First Edition 



1-16 



INTRODUCTIDN TO BIND AND EPFS 



• A program EPF can be constructed to selectively enable or 
disable most forms of command-line preprocessing performed by 
FRIMDSf such as wildcards, treewalking, iteration lists, and 
name generation. 

• A program EPF can obtain information on what kind of command 
preprocessing is taking place for the invocation of the EPF. 
For example, a program EPF can determine v*iether it is being 
invoked with a wildcard specification, even though what it 
receives as a command line argument is an object name without 
wildcards; if wildcarding is being used, the program may wish 
to alter its output display to suit a list of file system 
objects. 

• Program EPFs can be stacked on the oomnand processor stack, 
allowing you to invoke program A, suspend it (via Control-P for 
example) , invoke program B, and then, when program B finishes, 
use the STMT command to continue execution of program A at the 
point at which you suspended it, Ihis same mechanism applies 
when program A is suspended as a result of a programming error 

(such as a memory access violation or use of an illegal segment 
number), allowing easier program debugging by using more 
advanced debugging techniques. 
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• IRIMDS maintains an EPF cache for each user. Terminated program 
EPPs are not immediately ronoved from memory, but instead are 
placed in the EPF cache. A subsequent invocation of a program 
EPF that is in the EPF cache results in faster startup time for 
that EPF, because most of the initialization of the EPF has 
already been completed. HIIWDS keeps the EPF cache from 
overloading system resources ty ranoving older EPFs from the 
cache (and also from memory) as new EPFs are invoked. 

• An EPF contains not only procedure code and linkage information, 
but general information on the EPF itself, including: 

- Tlie version of BIND that was used to link the EPF 

- The date and time the EPF was linked via BIND 

- The name of the program, which may be dif feroit from the 
name of the file containing the program 

- The version of the program, as assigned ty the programmer 
during the BIND session 

- A comment pertaining to the program, as assigned ty the 
programmer during the BIND session; for example, a 
oopyri^t notice 

• Debugging of an EPF that is in production mode is easier; after 
an EPF is suspended, due to a user quit or some error, you can: 

- Use the LIST_EPF command to determine where in memory the 
EPF is located 

- Use the DUMP_sriOC command to display the stack history 
of the EPF and the HlI^DS command environment 

- Use BIND, which itself is an EPF, either to display a map 
of the EPF at the terminal or to write one into a file ty 
typing: 



BIND -LOAD EPF-filename -MAP [map-filename] -QUIT 



(With SBG and LOAD, you cannot generate a map of the 
program without destroying part or all of the in-memory 
copy of the suspended program.) 

Use VPSD, which ranains a static-mode program, to examine 
the EPF in memory. VPSD does not overwrite your EPF as 
it may static-mode programs; you no longer have to 
consider whether to use VPSD or VPSD16. Note, however, 
that you cannot place breal^x>ints in the procedure code 
of either a library EPF or of a program EPF that has been 
invoked via RESUME, because the pure procedure code is 



First Edition 1-18 



IMRODUCriDN TO BIND MD EPFS 



protected against writing. (Use the VPSD subcxnnmand of 
EBG if you wish to place breakpoints in the procedure 
code of an EPF with VPSD.) 

- Use other commands, such as ED, SKKIi, and so on, without 
disturbing the in-manory copy of the EPF or the stack 
history of tiie EPF. After invoking static-mode programs, 
you must issue the RELEASEJjEVEL command (abbreviated 
RLS) once to prevent a subsequent STM^T command fran 
returning you to the static-mode progrsm rather than your 
EPF. However, avoid issuing commands such as 
PELEfiSEJiEVEL -ALL and INrriALIZE_CDMMfiND_JNVIRCNMENT 
(abbreviated ICE) , as these delete stack history and, in 
the case of ICE, remove EPFs from memory. 

• The detection of uninitialized variables is iiiproved because, 
unlike SBG, BIND and PRIM3S do not initialize uninitialized 
static data to all zeroes for EPFs. While this may produce the 
undesirable effect of a working program failing when converting 
from using SBG to using BIND, it does significantly improve tiie 
chances of the prograraner detecting cases of uninitialized 
variables when a program is built as an EPF. When such a 
program does not depend on default initialization to zeroes, it 
is more portable in that it can be ported to hosts whose own 
operating systems do not provide default initialization. 

As you read on in this volume, particularly Chapters 2 through 6, you 
may discover additional benefits of using BIND to create EPFs. For 
information on features provided by EPFs when interacting with the 
PRBDS command environment, see Volume III of this series. 
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Mechanism 



This chapter e35>lains the concepts of tiiie dynamic linking mechanism, 
and details its operation. Because this mechanism is used ty all 
programs and libraries, all readers of this guide ^ould understand how 
it operates. A tiiorough understanding of dynamic linking on Prime 
systems iirproves one's ability to solve product design and packaging 
problems while it simplifies the debugging of errant programs. 



WHAT IS THE DYNftMIC LINKIN3 tECHMISM? 

Bie dynamic linking mechanism in IRIWDS allows a program to call 
subroutines that are not linked in with the program itself, but which 
are located in one of several libraries when the program is run. The 
advantages of placing subroutines in libraries that are connected fcy 
the dynamic linking mechanism, rather than binding them into each 
program that uses them, are: 

• Less disk space is wasted because only one copy of tiie 
subroutine exists on a systan, rather than having a copy in 
every program that uses the subroutine. 

• Less memory is needed when two or more users are running 
programs that use the same subroutine, because the subroutine is 
automatically ^ared betweoi users. 

• New versions of the subroutine can be easily installed, as long 
as they are compatible with previous versions, without having to 
relink all programs that use the subroutine. 
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• Internal privileged ERIIDS subroutines, which execute in ring 0, 
can be accessed via the dyramic linking mechanism if tiiey are 
entrypoints into IRIMDS; special-purpose supervisor call 
instructions need not be used. 

There are three general types of subroutine libraries in ERIMDS: 

• PRIMDS-residsnt libraries, containing subroutines that are 
internal to PRIMDS, 



Library EPFs, supplied by Priite or by vendors, or 
these are described in Chapter 6. 



user-written; 



• Static-mode shared libraries, supplied only by Prime. 

"Hie dynamic linking medianism allows access to specific subroutines, 
called entrypoints , in these three types of libraries. Although a 
particular library nay have several subroutines, a subset of these 
subroutines may be declared by the library as entrypoints; only 
entrypoints may be called by programs that reside outside the library 
itself. 



WHAT IS A D1^NAMIC LINK? 

The crux of the (^namic linking mechanism is the dynamic link , also 
called a pywr (pronounced "dint") . In place of a normal pointer to the 
BCB of a subroutine, a dynamic link consists of a special pointer, 
called a faulted IP (Indirect Pointer) , that points to the name of an 
entrypoint. The dynamic link serves as a placeholder for a subroutine 
until that subroutine is located and connected to the program; it 
contiains the name of the subroutine. 
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WHAT HAPPENS TO A DYNAMIC LINK? 

When a program is run, it attenpts to use faulted IPs when calling 
subroutines external to the program. Each time a faulted IP is 
encountered, a fault condition results; this causes PRIMDS to call its 
d/namic linking mechanism to resolve tixe fault condition. 
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The dynamic linking mechanism examines the faulted IP, determines that 
it is part of a dynamic link, and begins a complex process that 
culminates in the determination of the actual IP of the BCB of the 
target subroutine. HRIMDS then replaces the faulted IP with the actual 
IP; this is called snapping the link. At this point, ERIM3S resets 
the fault condition and continues the program. The instruction that 
caused the fault by referencing the faulted IP is executed again, and 
it succeeds: the target subroutine is called. 
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HOW DOES ERIM3S SNAP THE LINK? 

TO determine the name of the target subroutine, IRIMDS modifies the 
faulted IP so that it is a normal IP by resetting the Fault bit in the 
IP. (PRIMDS does this to a temporary copy of the IP, not the copy in 
memory tiiat caused the fault.) Then, FRIMOS uses the resulting IP to 
read, from memory, the name of the target subroutine. (The name is 
stored in CEIARACTER VARYING format. ) 

Once miVDS has the name of the target subroutine, it searches through 
its list of libraries (all three types) for a library that declares 
that name as an entrypoint. When ERIMDS finds the first such library, 
HIIM3S performs whatever initialization of that library is needed (such 
as initializing ECBs, IPs, static data, and so on) . Then, ERIMDS 
determines the actual address of the ECB of the target subroutine 
within that library and replaces the faulted IP with tiiat actual 
address. 
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SAMHiE SESSION 

The following annotated sample session illustrates the effects of the 
d/namic linking mechanism. A program named LINKIT is written which 
first sleeps for ten seconds and then calls the TIOJ subroutine. The 
ten-second sleep allows the user to type (XXmROL-P before the TIOD 
subroutine is called; the user can then examine (via VPSD) the faulted 
IP that will be used to call TIOJ, and can also examine the name of the 
target subroutine (the TICU DXNT) . 

The user tiien terminates VPSD, types STi^RT to continue execution of 
LINKIT, and waits for the program to finish. After the program 
finishes, the user examines the IP again and sees that it is no longer 
faulted, but instead points into the linkage area for the library EPF 
named SYSTHUiIBRARY, as ^own by an ensuing LIBT_JI>F command. (The IP 
points into the linkage area rather than the procedure area because a 
resolved IP to a subroutine points to the ECB of that subroutine; the 
ECB itself actually points to the first executable instruction of the 
subroutine.) 



OK, m 
INPUT 

SUBROUTINE LINKIT 

CALL SLEEP$ (010000) /* SLEEP FOR 10 SECONDS 

CALL Tiaj(;207) /* RIN5 THE BELL 

RETURN 



END 



(CR) 

EDIT 

FILE LINKIT. FIN 

OK, FIN LINKIT -DYNM -DCL 

0000 ERRORS I<LINKIT>FTN-REV19.3] 
OK, BIND -LOAD LINKIT -LIBRARY 

[BIND rev 19.4] 

BIND OOMH.ETE 

OK, INITIALIZEJI)M^ffiND_J^lVIRC^lMENT (cleans up enviroment) 

OK, RESUME LINKIT 

(user types Control-P after a few seconds elapse) 

(3UIT. 

OK, LJffUJEPF -DETAIL (shows placement of program in memory) 

1 Program EPF. 

(active) <USRDSK>UN3ER>LINKIT.BUN 

1 procedure segment: +0:4340 
1 linkage area: -2:4377(3)/70 

bind version: 19.4 

date of binding: 84-11 -13 .16: 38: 40, TUe 
program name: LINKIT 

user version: (none) 

comment : (none) 

debug segments: 1 
ccmmand options: wldcrd, trwlk, iter file,dir,segdir,acat 1 
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OK, VB5D (use the symbolic debugger to examine memory) 

$SN 4340 (the procedure aegnent) 

$A 1000 ;S (EPFs typically start at offset '1000; see map) 
4340/ 1000 PCL% IB%+ 422,* (CR) (the SLEEP$ call) 
4340/ 1002 AP 1012, SL (CR) 

4340/ 1004 PCL% IB%+ 424,* (CR) (the TlOU call) 
4340/ 1006 AP IB%+ 400, SL (CR) 

4340/ 1010 mm i 

$IB 4377 70-400 (linkage references are offset by '400) 

$A LB%+424;0 (access the faulted IP) 

4377/114 104340 (CR) (the fault bit is the 1 in 104340) 

4377/ 115 1014 i 

$SN 4340 (select the segnent, without the fault bit) 

$A 1014 

4340/ 1014 4 \K (name of D5fNT is four characters long) 

4340/ 1015 11 (CR) (name of Dmr is TlOU) 

4340/ 1016 OJ 7r~ 

OK, RELEflSEJLE^^EL (release the static-mode VPSD invocation) 

Static mode program released, (rls) 

OK, START (continue the suspended invocation of LINKET) 

(bell rings) 

OK, VPSD (reoiter VPSD) 

$IB 4377 70-400 (set up IB again) 

$A IB%+424;0 (access the same place in memory) 
4377/114 4377 (CR) (IP now points to 4377A6304) 
4377/ 115 16304"7~^ 

OK, LIST_EPF -DETAIL -N3_WAir (check for library EPF) 

1 Process-Class Library EPF. 

(active) <S^DSK>LIBRARIES*>SYSTEIlJiIBRARY.FDN 

2 procedure segnents: +0:4342 +2:4343 

2 linkage areas: -2:4376(0)/0 -4:4377(3)A134 

bind version: 19.4 

date of binding: 84-10-25. 16: 17: 20 .Tliu 
program name: SYSTB^OjIBRARY 

user version: (none) 

comment : Copyric^t (C) 1983, Prime Computer, Inc., 

Natick, Ma. 01760 All ri^ts reserved 
debug segnents: 2 



1 Program EPF. 
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(not active) <USRDSK>UN3ER>LINKIT.FUN 
1 procedure segotient: +0:4340 
1 linkage area: -2:4377(3)/70 

bind version: 19,4 

date of binding: 84-11 -13. 16:38:40 .Tue 
program name: LINKIT 

user version: (none) 

comment : (none) 

debug segments: 1 
command options: wldcrd, trwlk, iter f ile, dir, segdir, acat 1 



OK, 



WHAT IF THE DESIRED SUBROUTINE CRNN3T BE FOUND? 

Eynamic links, also referred to as faulted IPs, are resolved as the 
program runs. They are resolved to point to one of the three types of 
libraries discussed previously. If none of the libraries known to 
ERIM3S lists a particular subroutine as an entrypoint, ERIMDS signals 
the error condition LINKAG^FAULT$. Unless intercepted fcy a program, 
the condition results in a dispLer/ similar to the following: 

Error: condition "LINKAGELFAULT$" raised at 4243(3)/1031. 
Entry name "INir_JjINE" not found while attempting to resolve 
dynamic link from procedure "TR^CJVSYNC" . 
ERl 



Here, INXT-JLINE is the target subroutine that is not known to ERIMDS, 
424V1031 is the address of the instruction that referenced a faulted 
IP for INrr_JiINE, and TRlCJfi^fNC is the name of the procedure making the 
reference. 



Note 

IRIM3S is not always able to determiiie the name of the 
procedure making the reference that produces the linkage fault 
error. For example, procedures compiled in FTOI do not identify 
themselves to ERI^DS; therefore, FRIWDS produces a shorter 
message. For example: 



Error: condition "LINKfiGEJ'ADLT$" raised at 4347(3)A0246, 

Entry name "GETLIN" not found. 

ER! 
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HOW DOES DYNAMIC LINKING RELATE TO 00MM3N BLOCKS? 



IRI^DS does not support dyramic linking to oonnnon blocks? dynamic 
linking to subroutines only is supported. The BIND subcommand 
EIWRYNA^E -ALL applies only to subroutines; ENTRYNAME -ALL does not 
declare common areas in a library EPF as externally available 
entrypoints. 



Caution 

Do not explicitly name a common area in a D5fNT or EMTRYNA^E 
subcommand in BIND, or you may encounter unexpected results. 
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This chapter describes the EPF mechanism itself. You should read this 
chapter if you want to more thoroughly understand how EI^s are handled 
by BRI^DS. 

TSiere are three general areas with vdiich the EPF mechanism is 
concerned: 

• Memory allocation 

• Subroutine linkage 

• Data initialization 

In terms of these three general areas, this section describes: 

• The organization of an EPF 

• The organization of subroutines on Prime ^irstems 

• The life of an EPF 

• How multiple invocations of an EPF are handled 

• How simultaneous use of an EPF by two or more users is handled 

• How to debug an EPF using IBG 

• Hew invocation of a remote EPF is handled 
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EPF ORGANIZATION 

A running EPF is organized into five basic sections: 

• Procedure text 

• Linkage text 

• Stack space 

• Dynamically allocated inanory (optional) 

• Debugger text (optional) 

Not all of the information in these five sections exists before the EPF 
is invoked. Ihe file containing an EPF, named program . HJN or 
program . RPn/ contains only the following information: 

• Procedure code 

• Linkage text initialization information 

• Stack allocation information (included in linkage text) 

• Debugger text 

Procedure Code 

The procedure code for an EPF is the most stable aspect of an EH". 
Once a procedure is compiled or assembled, the contents of the 
procedure code are set. Once an EPF is linked by BIND, the pure 
procedure segments of that EPF are set and are not changed. An EPF may 
also have iirpure procedure segments; the oontoits of an iirpure 
procedure segnent may be changed fcy FRIMDS or hy the program itself as 
it runs. Typically, a procedure segnent is iirpure because it contains 
linkage data (such as ECBs or IPs) , although it may be iirpure because 
the code actually modifies itself as it executes. 

Linkage Text 

The linkage text for an EPF is the most complex aspect of an EPF. 
Linkage text includes: 

• Program data 

• ECBs for subroutines 

• Links betweai subroutines 

• Links to common data areas 

• Common data areas 
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The final content for this infonnation is determined at different 
points in time during the life of an EPF, depending upon the nature of 
the infonnation. Because all of this information resides in the inpure 
part of an EW, and most of it resides in the Linkage text of an EPF, 
various portions of the linkage text of an EPF are finalized at 
different points in time during the life of that EPF. Therefore, the 
file containing an EPF rarely contains the final content of the linkage 
text; instead, it contains a combination of final information and 
information on how other portions of the linkage text are to be 
initialized. 

Although common data areas are, themselves, not part of the linkage for 
any particular procedure, BIND places them in the linkage portion of an 
EPF along with the linkage text. 



Stack Space 

As noted, the stack allocation infconation is stcared in the linkage 
text. Stack is allocated automatically during the invocation of a 
subroutine via tiie PCL (Procedure Call) instruction; the ECB for a 
subroutine includes the amount of stack space to be allocated each time 
the subroutine is called. Therefore, stack allocation is performed 
each time a subroutine is called. 



Dynamically Allocated Memory 

E^naniically allocated memory is acquired during program execution as a 
result of ejqjlicit requests by the procedure code of the program. 

Because both stack storage and ^mamically allocated memory are 
acquired during program execution, the file containing an EPF does not 
specify initial values for data within those areas. In fact, data in 
stack storage or in dj^namic storage must be initialized during program 
execution. 



Debugger Information 

Information provided via the -DEBUS c^ion of most Prime-supfiLied 
compilers is also kept in an EPF. EBG alone uses this information 
during the debugging of an EPF. You do not need to be concerned with 
the nature of this information, as long as you understand that it is 
passed from the compilers to BIND via object (.BIN) files, and from 
BIND to EBG via the EPF. 
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SUBROUTINE OBGMIZATroN 

Tlie Prime 50 Series architecture defines a subroutine, or procedure, as 
consisting of: 

• Procedure code 

• Linkage text 

• Stack space 

• An Entry Control Block (ECB) that contains information on the 
above three elanents 

A particular procedure is said to consist of a procedure frame , a link 
frame , and a stack frame , which correspond to the terms listed above. 

Management of the elanents of a procedure is handled at runtime ty the 
PCL and PKIN instructions. To call a procedure, a PCL instruction that 
addresses, as its target, the ECB of the desired procedure, is 
executed. The PCL instruction analyzes the ECB for the procedure being 
called, allocates a stack frane, and handles the tiransfer of arguments 
between the procedures. Befcxre the PCL instruction completes, it sets 
up three base registers (PB for Procedure Base, IB for Linkage Base, 
and SB for Stack Base) pointing to the three frames listed above. 
These base registers are used fcy the procedure being called during its 
execution to execute instructions and access data in its linkage and 
stack areas. 

A procedure therefore consists of only one copy of its procedure code 
and link frame, whereas it has any number of stack frames, depending 
upon the number of active invocations of that procedure. The EPF 
mechanism, however, provides a method for maintaining more than one 
copy of the link frenies for an entire EPF when appropriate. Each 
separate invocation of a program EPF is given its own copy of its link 
frames by the EPF mechanism; similarly, each use of a program-class 
library EPF by a separate program invocation is given its own copy of 
its link frames. (See Chapter 6 for information on library BIT'S. ) 

At the beginning of each stack frame is a stack header that contains 
the information needed to identify the owning procedure and also the 
information needed to return to the calling procedure. The stack 
header may also contain information on conditions and on-units to be 
invoked; this information is defined and set up by software on the 
Prime 50 Series systems. 

When the called procedure is finished, it executes the IRTN 
instruction. The PRTN instruction deallocates the stack frame used by 
the procedure, resets the three base registers to their original values 
(before execution of the matching PCL instruction) , and returns control 
to the calling procedure at the instruction following the PCL 
instruction (and its argument list, if any) . 
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Typically, the linkage infonnation for a prcxzedure also oontains the 
ECB for that procedure. It may seem strange that tiie ECB for a 
procedure not only identifies the address of the link frame of that 
procedure but also resides in the same link frame. It is the calling 
procedure that must address the ECB of the target procedure; the 
calling procedure does this ty specifying an indirect pointer, or IP, 
that resides in its own link frame. TMs IP is set by either BIND or 
PRI^DS to point to the target ECB. Because an IP is a full address, 
rather than an address relative to the IB, IB, or SB base registers, 
the ECB may reside in the link frame of the target procedure. 

General information on the procedure call medianism is found in the 
Prime 50 Series Technical Summary . Details of the procedure call 
mechanism, including formats of the ECB and stack frame, are found in 
the System Architecture Reference Guide . 



OHE LIFE OF AN EPF 

In the following discussion, the life of an EPF is presented as a 
series of phases through which an EPF passes from generation by the 
programmer, through invocation by a user or program, through 
termination, to ranoval from memory. Each of the above three areas is 
touched upon during the description of the phases. 

In very general terms, the life of an EPF can be seen as progressing 
through five stages: 

1. Generation by the programmer 

2. Invocation (by a user or by a program) 

3. Preparation by IRIIDS 

4 . Execution 

5. Ranoval by PRI^DS 

Each of these stages consists of one or more phases that, vAien put 
together, constitute a complex series of steps in the life of an EPF. 
Some of these phases differ in meaning between types of EPFs. For 
example, a program EPF is invoked directly by a user or program, 
whereas a library EPF is invoked as a result of a call to one of its 
entrypoints by another running program. 

Prime-supplied text editors and cranpilers, the Prime Macro Assanbler 
(PMA) , and the BIND linker perform the activities that constitute Stage 
1 at the direction of the programmer. After Stage 1, the EPF is in the 
hands of its users and is operated on by FRIMDS. 

As described in Volume III of this series, there are many 
HRIPDS-supplied subroutines that operate on an EPF. One subroutine, 
EPF$raJN, performs all of the tasks needed to invoke a program EPF. 
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Invocation of an EPF, whether by EPF$HDN (for a program EPF) or by 
calling one of its entrypoints (for a library EPF) , is Stage 2 in the 
above list. 

EPF$RDN performs its tasks ty calling other EPF$ subroutines to prepare 
the EPF for execution (Stage 3) , to execute the EPF (Stage 4) , and to 
remove the EPF from memory (Stage 5) . 

All five stages apply eqially for both types of EPFs, Library EPFs, 
however, are not executed in the same way as program EPFs; instead, 
the subroutines they contain are executed as the calling progran 
invokes them, 

OJie other EPF$ subroutines called ty EPF$R[JN are called fear every EPF 
run by ERIMOS. The exception is the EPF$INVK subroutine, which invokes 
a program EPF, 

To describe the EPF mechanism faithfully, only those phases that are 
generally common to both program EPFs and library EPFs are presented 
here. Where appropriate, each step is correlated with the appropriate 
EPF$ subroutine. Chapter 6 describes aspects of the mechanism specific 
to library EPFs; Volume III of tiiis series describes the EPF$ 
subroutines, including EPF$RUN, in detail. 

•Hiere are ten phases of activity during the life of an EPF: 

1. The procedures that are to constitute the EPF are compiled or 
assembled, generating object files (.BIN files). 

2. Tliese object files are linked using BIND, generating an EPF. 

3. The EPF is invoked by either a user or a running program 
(EPF$RUN or the dynamic linking mechanism) . 

4. The procedure (pure) portion of the EPF is mapped to manory 
(EPF$MAP) . 

5. "Hie linkage (impure) portion of the EPF is allocated 
(EPF$ALLC) . 

6. The linkage (impure) portion of the EPF is initialized 
(EPF$INIT) . 

7. The EPF entrypoint is invoked (EPF$INVK or the dynamic linking 
mechanism) . 

8. Eynamic links encountered within the EPF are snapped. 

9. The EPF terminates, returning to its caller. 
10. The EPF is removed from memory (EPF$DEL) . 

The remainder ot this diapter describes these phases in detail. 
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Phase 1 - Compiling or Asseinbling 

The source cx>cle of the program or library specifies the exact contents 
of the procedure text and the desired oontoits of the linkage text. 
Ihe purpose of this phase is to generate an object file containing this 
infonnation in a form that is independent of the language used in the 
source code. 

Procedure text includes instructions and often includes constants used 
during execution of the procedure. Linkage text includes: 

• Static data, which can be initialized when the program is 
invoked (via POKCRAN EATA statement or PLl/G STATIC INITIAL 
attributes) 

• The BCB for the procedure and an ECB for each alternate 
entrypoint and for each internal procedure 

• External linkage infonnation, such as pointers to external 
procedures or to common areas 

Static data values are known during this phase. Most of the data in an 
ECB are known during this phase except for the actual location of the 
procedure frame and the linkage frame for the procedure. The data fee 
external linkage infonnation are not known during this phase. 

Data that are not known during this phase are described using alternate 
methods. For example, the statement CALL SUBPl mi^t reference an 
external procedure named SUBRl. The external linkage information 
indicates a requiranent for an IP (Indirect Pointer) to SUBRl at a 
certain location in the link frame. Either BIND or IRIDOS sets the 
data value of the IP. The procedure code, which is knam during this 
phase, includes a PCL instruction referencing the location of the IP in 
the link frame as an indirect reference. Figure 3-1 illustrates 
linkage information as it exists in a single object (.BIN) file. 

In Figure 3-1, the procedure SUBPl references six external symbols: 
SUBR2, OOMNl, GC»4N2, SRCH$$, CLOS$A, and SPOCL$. Figure 3-2 
illustrates linkage information for the tiiree object files, including 
SUBR1.BIN, that will be used to build a program EPF. 



Phase 2 - Linking 

Ctoject files are linked together using BIND during this phase. BIND 
maintains a list of procedure (PROC, or pure) segnents and linkage 
(DATA, or iiipure) segnents needed to represent the resulting program. 
The purpose of this phase is to produce an EPF file that contains the 
PROC, IMPURE, and DATA segnents needed to run the program or library. 
Also, debugger infonnation is written to the EPF file v*ien this 
information is provided in the object files. 
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-ENT SUBR1-| 




EXT IP SUBR2 
EXT IP COMNl 
EXT IP C0MN2 
EXT IP SRCH$$ 
EXT IP CLOSiA 
EXT IP SPOOL* 



SUBR1.BIN 

ENT is an externally available name declaration 
EXT IP is an external (unresolved) Indirect Pointer 



Linkage Information in a Single Object File 
Figure 3-1 
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Linkage Information in Three Object Files 
Figure 3-2 
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The procedure code from the linked object files is collected into one 
or more EROC and IMPURE segments. Link frames from these object files 
are collected into one or more DATA segments. Common areas referenced 
(and optionally initialized) by these files are also placed in DATA 
segments. 

While collecting link frames, BIND maintains a list of external sytitools 
and their placement in the program so that it can resolve some of the 
references in the link frames. 

For example, if the CALL SUBRl statement exists in a program named 
PROG, and the BIND session to create PROG.HJN links SUBRl in with it, 
BIND resolves the IP to SUBRl in the link frame of FROG to point to the 
SUBRl BCB in the linkage text of SUBRl. 

However, in most cases, BIND cannot resolve IPs to the actual raanory 
addresses. Each time an EPF is invoked, IRIMDS dynamically allocates 
manory for the linkage text of the program. Therefore, BIND does not 
know the actual memory address of the linka^ text of SUBRl, and 
therefore cannot compute the actual memory address of the SUBRl BCB. 

Instead, BIND leaves the task of determining actual memory addresses to 
IRIM3S. BIND identifies all IPs and ECBs that must be adjusted at 
program runtime by ERIMDS. In the meantime, BIND uses imaginary memory 
addresses. An imaginary address identifies a location within a 
particular EPF. When an EPF is invoked, ERIJDS maps the EPF into 
virtual memory and maintains a table indicating the mapping between 
imaginary and actual addresses. 

In our example, therefore, BIND mi^t put the linkage text for SUBRl at 
imaginary address -000:^60. (Due to the architecture of Prime 50 
Series computers, linkage text starts at octal 400 halfwords beyond the 
address in the base register that identifies linkage text for a 
procedure. Therefore, if linkage text is at -000?/60, the address used 
by BIND must be -000^177460, because 60 minus 400, in octal and using 
16HDit unsigned halfword arithmetic, is 177460.) 

If the BCB for SUBRl begins at octal 120 hal&/ords beyond the start of 
the linkage text, then the imaginary address for the ECB is -000^200. 
BIND places -0002/200 in the linkage text location for the IP needed ty 
PROG when it calls SUBRl so that it uses the SUBRL BCB as its target. 
BIND also places -000^177460, the offset start of the SBRl linkage 
text, into the appropriate portion of the SUBRl ECB. In both cases, 
BIND identifies that it has used imaginary addresses in the file 
containing the EPF, so that when the EPF is invoked, IRIM3S knows to 
modify these addresses. 

BIND uses segment numbers +0, +2, +4, +6, +10, +12, and so on to 
indicate imaginary addresses identifying pure procedure (PROC) 
segments. BIND uses segment numbers -2, -4, -6, -10, -12, -14, and so 
on to indicate imaginary addresses identifying linkage (DATA) segnaents 
or impure procedure (IMPURE) segments. For more information on 
.imaginary addresses vs. actual addresses, see Chapter 9. 
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Figure 3-3 illustrates the resolution of some of the external syittol 
references made by the three object files after BIND is invoked and the 
three files are linked via the LOAD subcommand. 

As illustrated in Figure 3-3, external refer oices to SUBPl and SLIBR2 
have been resolved to the extent that their placement relative to the 
start of the EPF itself is known. There is only one way to produce 
actual memory addresses in BIND, and that is fcy using the SliMBCL 
subcommand. 

When you use the S^MBCL subcommand to tell BIND exactly v^ere an 
external symbol is located in memory, BIND does not use an imaginary 
address. Instead, it replaces all of the program's unresolved IPs that 
reference the external sytitool with the actual address you specified 
using the SYMBOL command. Because use of the SYMBOL coranand requires 
you to manage actual memory, its use is generally confined to 
specifying ^ared common areas, as described in Chapter 8. 

The SYMBOL subcommand may also be used to specif;^ a common area in 
static per-user memory. Figure 3-4 illustrates this use of the SYMBCL 
subcommand. 

In Figure 3-4, the SYMBOL subcommand is used to specify that the common 
area named 00MN2 is placed at address 4001/0, v4vich is in static 
per-user memory. BIND therefore fully resolves all external references 
to CX)MN2 to actual memory addresses. 



Note 

Common areas that are placed ty the SYMBOL subcommand of BIND 
are not initialized ty BIND during program linking or by HRIMDS 
when the program is invoked. Either the program must 
initialize the common area at runtime, or it must be 
preinitialized by another program (as is of toi the case when 
shared memory is involved) . 

External references still unresolved include references to SRCH$$, 
CLOS$A, and SKXJL$. These are Prime-suppLied subroutines that reside 
in libraries. These references are resolved when the libraries are 
linked via the LIBRARY subcommand of BIND. However, they are resolved 
only to the extoit that they are identified as dynamic entrypoints, 
also known as dynamic links. IPs to these subroutines are converted to 
faulted IPs by BIND, as illustrated in Figure 3-5. 

A faulted IP has a bit, called the fault bit, set to 1. This causes a 
hardirare fault to take place v*enever the IP is referenced as an 
indirect pointer, as described in Chapter 2. With the fault bit in the 
IP reset to 0, the IP points to a DYOT that names the desired 
subroutine. Because this name is in the EROC code of an EPF, BIND must 
use an imaginary address in the faulted IP as it does for other 
addresses not set using the SYMBOL subcc^nmand. 
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After Linking (Loading) Tliree Object Files in BIND 

Figure 3-3 
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After Using the SYMBOL Subxunrnand in BIND 
Figure 3-4 
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LIBRARY VAPPLB 
LIBRARY SPOOLS 
LIBRARY 



-•-ENT PROG 




-ENT SUBRl 



ENT S0BB2 - 



jaE^IP SUBRl - 

JSET IP SUBR2 ■ 

IP SRCH»$ 

IP CLOS$A 




-*^ 



D 




iserip SUBR2- 

EXT IP COMNl 

IP C0MN2 = 4001/0 
IP SRCH$$- 
IP CLOS$A. 
IP SPOOLl . 



EXT IP COMNl 
I^H IP C0MN2 : 



: 4001/0 



IeXTI IP GLOS$A — . 




|EXT| IP is a faulted pointer. 
DYNT is a dynamic-link declaration. 



After Using LIBRARY Subcommands in BIND 
Figure 3-5 
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There still rernain two unresolved references to the GOMNl oornmon area. 
BIND knows the size of the coinmon area, because this information was 
provided in the object files that referenced the coinmon area. Hcwever, 
BIND has not yet resolved the two external IPs to CDMNl, because it 
does not yet know whether CDMNl is part of the EPF, or external to the 
EPF (as defined by the S"XMBCL subcommand) as is G0MN2. Once the FILE 
subcommand is given, BIND resolves the diloraia hy placing any 
unresolved common areas within the LINK portion of the EPF and 
resolving IPs to the common areas to imaginary addresses. 

However, if you wish to produce a MAP of an EPF before issuing the FILE 
subcommand, you may want the imaginary addresses produced for such 
common areas to be present in the map. To effect this, issue the 
RESOjVEJSIFEFREILCDMMDN subcommand of . BIND before issuing the MRP 
subcommand of BIND. Figure 3-6 illustrates the effect of the 
RESCTiVEJKFERRED_OOMMDN subcommand on IPs to CDMNl and on the EPF 
itself. 

As shown in Figure 3-6, BIND has allocated storage in the EPF for the 
OOMNl common area, and resolved IPs to (XmO. so that they point to this 
area. Although not shown, GCMNl is located in the LINK portion of the 
EPF. TSie IPs to OOMNl are imaginary addresses, because the final 
address for GOMNl is not known until after the EPF is invoked. 

Although all external IPs have been resolved in seme fashion, there 
remains the task of defining the entrypoint or entrypoints to the EPF. 
A program EPF has only one entrypoint, defined ty the MAIN subcommand 
of BIND, as illustrated in Figure 3-7. A library EPF has one or more 
entrypoints, defined ty the ENTR™A^E subcommand of BIND, as described 
in Chapter 6. 

Figure 3-7 illustrates the final EPF file produced ty a FILE subcommand 
after the entrypoint (s) of the EPF have been identified. fRIMDS uses 
the MAIN or EMKYNAfE entrypoints when invoking the EPF. If no MAIN 
subcommand is given while linking a progrcm EPF, BIND uses the first 
module linked via the LOAD subcommand as a default. If no ENTRYNA^E 
subcommand is given while linking a library EPF, the library EPF is 
effectively useless because the dynamic linking mechaniam will not link 
to any subroutines contained in it. 

Figure 3-7 also illustrates that, once the EPF is written to a file, 
the boundaries between procedures are less distinct; BIND assembles 
the procedure frames and link fremes for the procedures into single 
procedure segments and link segments for use hy HRIMDS. Generally, 
^RI^DS is not aware of the boundaries betweoi procedures within an EPF; 
PRIM3S is more concerned with the boundaries between EPFs in manory. 



Phase 3 - EPF Invocation 

When an EPF is invoked, ERIIDS begins the process of preparing the EPF 
•so that it can be executed. Portions or all of this process may be 
avoided, however, if they have been performed previously. 
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The fonn of invocation depends upon the type of the EPF. A program EPF 
is invoked ty calling the EPF$RDN subroutine or by calling the CP$ 
subroutine to execute an EPF, (CP$ is called to process a user command 
such as RESUME; it calls the same EH'$ subroutines that EPF$RUN 
calls.) A library EPF is invoked by a program that references one of 
its entrypoints ty name. 

Once IRIIOS has determined the name of the EPF to be invoked, it checks 
to see if it has already performed some or all of the preparatory steps 
needed to execute the EPF. For a program EPF, IRIMDS considers whether 
it must map the EPF to monory; if it has already mapped the EPF, it 
skips Phase 4, A program EPF is already mapped to manory if it is 
either on the EPF cache or if another, invocation of the same EPF is 
still active on the oomomand stack, such as when it is suspended ty tiie 
user. 

For a library EE^, miMDS has already mapped in the EPF at least to 
ciieck its list of oitrypoints to see if the desired subroutine is an 
entrypoint in the EPF. A library EPF is already mapped to memory, 
therefore, ty the time ERIICS determines that the EPF is the tiarget of 
a dynamic link, IRIPDS then determines whether Riases 5 and 6 may be 
skipped. See Chapter 6 for a complete description of how IRIMDS 
decides whether to skip phases 5 and 6 for a library EPF. 



Fhase 4 - Mapping 

During Phase 4, ERIMDS allocates sufficient dynamic segments to hold 
all of the pure procedure (HICX:) segnents required ty the EPF. The 
EPF^lAP subroutine performs the t:asks associated with this phase. 
InformatJ.on on space requirQnent:s for procedure and linkage segnents is 
found by JRIMDS in the file containing the EPF. 

IRI^DS maps the HlOC segments that have been allocated to the imaginary 
EROC segnent numbers (+0, +2, +4, and so on) used in the file 
ooni:aining the EPF, In fact, HIIMDS does not read the procedure text 
in from the file at this point — instead, FRIM)S uses the virtual 
manory mechanism of FRIMDS to page data for these segnents directly 
from the file containing the EPF. Because the virtual memory mechanism 
does not allow for segnents mapped in this way to be modified, FRIM3S 
set:s the access on these segnents so that they cannot be written by the 
user or the program itself. 



Phase 5 - Linkage Allocation 

During Hiase 5, HlIfDS allocates sufficient dynamic space to hold all 
of the linkage (DATA) segnents and impure procedure (IMHJRE) segnents 
required by the EPF. HRIMDS sets the access on these segnents so that 
they can be written ty the user or by the program. The EPF$AIJX: 
subroutine performs these tasks. 
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RESOLVE_DEFERRED_COMMON 
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Phase 6 - Linkage Initialization 

During Phase 6, ERIMDS reads the descriptor information for the linkage 
areas and irnpire areas of the EPF and sets the DATA and IMPURE segnents 
that have been allocated to contain the indicated inforination. Data 
such as program constants are copied directly into the DATA segments. 
Linkage data consisting of imaginary addresses are first converted into 
the corresponding actual addresses for this program invocation, and are 
then copied into the DATA segnents. This linkage data consists mostly 
of IPs and ECB linkage area pointers. Impure procedure code is copied 
directly into the IMPURE segnents, Biese tasks are performed ty the 
EPF$INIT subroutine. 

Figure 3-8 illustrates a program EPF after its imaginary addresses have 
been converted to actual addresses. 

Although Figure 3-8 illustrates the overall effect of a RESUME command 
on a program EPF just before its main entrypoint is actually invoked, 
the same actions are performed on a library EPF. All of the linkage 
information for both program EPFs and library EPFs is initialized, 
converting imaginary addresses to actual addresses for both IPs and 
ECBs. The only IPs that rannain unresolved are faulted IPs. Faulted 
IPs are adjusted so that they contain the actual addresses of ECTNTs, 
rather than the imaginary addresses produced by BIND. 



Riase 7 - Entrypoint Invocation 

At this point, PRIMDS either executes a VCL instruction to the ECB of 
the main entrypoint for a program EPF (performed by the EPF$INVK 
subroutine), or resets the fault condition and reexecutes the original 
POL instruction that now references the ECB of the desired entrypoint 
for a library EPF (performed ty the c^namic linking medianism) . Ihe 
EPF is now running. 
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Phase 8 - Dynamic Links Snapped 

During the execution of the EPF, faulted IPs are typically encountered. 
"Hiese represent dynamic links that must be snapped by ERIMDS before the 
inst:ructions referencing the faulted IPs can be executed. Once 
snapped, a faulted IP becomes an actual memory address, and subsequent 
use of that particular IP produces no fault condition. 

Because several different faulted IPs may point to the same DSTOT within 
an EPF, several faults may resolve to the same subroutine within an 
EPF. In addition, while sane entrypoints reside in ERIMDS, others 
reside in library EPFs or in static-mode libraries. To show the 
details of how dynamic links are snapped in an executing EPF, several 
illustrations are provided that follow the PROG program EPF through its 
execution until it has smpped all of its faulted IPs. 

In practice, few programs ever snap all of their faulted IPs, because 
some faulted IPs point to error-handling subroutines (such as EEUIER$ 
and SIGNL$) , v*iile other faulted IPs point to subroutines used when no 
errors occur (such as INCXJ, HWF$$, and CLOSSA) . Furthermore, a 
library EPF rarely snaps all of its links when it consists of more than 
one entrypoint, unless each entrypoint in that library EPF is invoked 
by the same calling program during its execution. 
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Figure 3-9 illustrates the PROG progran EPF after the first dynamic 
link to SRCH$$ in the PROG procedure is snapped. Here, ERINDS itself 
is illustrated as residing in the same memory space as the user program 
and containing many entrypoints, one of which is named SRCH$$, 

In Figure 3-9, the first faulted IP in the EPF, which resides in the 
link frame for FROG, has been snapped. It has been replaced with the 
absolute address of the ECB of SRCH$$ in HlI^DS. Note that another 
faulted IP to SRCH$$, in the link frane for SUBRl, has not been 
resolved. 

Dynamic links to entrypoints in PRIMDS itself are easy for IRIM3S to 
resolve. ERI^DS is always present in every user's memory address 
space. In addition, all HRIMDS entrypoints have their link frannes 
initialized at system ooldstart or during systan fcuild, so no 
initialization is needed. 
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Dynamic Link to SRCH$$ in PROG is Snapped 
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Next, a faulted IP to CLOS$A in the PRCG procedure is snapped. CLOS$A 
is an entrypoint in the i^lication Library (described in the 
Subroutines Reference Guide ), which is contained in the library EPF 
file LIBRfiRIES*>APHiICAT]DlU^IBRfiRY.FDN. Figure 3-10 illustrates the 
appearance of the PROG program EPF after the dynamic link to CI/DS$A is 
snapped. 

As shown in Figure 3-10, the APPLICATIDNJilBRARy library EPF has been 
loaded into memory and "connected" to the running program EPF mCG. In 
fact, by the time the first call to CLOS$A by the FRCG procedure was 
completed, the library EPF named APILICATnDliJilBRARy went through 
E*iases 3 through 9 as described here, vrt^n the CLOS$A entrypoint 
returned to its caller, the PROG procedure. 

Again, notice that two other faulted IPs to CLOS$A, in SUBRl and in 
SUBR2, have not yet been resolved. 

Sometine after calling SRCH$$ and CLOS$A, the PROG procedure calls the 
SUBRl procedure, which will encounter its own faulted IPs. 
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Dynamic Link to CLOS$A in PROG is Snapped; APPLICATION_LIBRARY.RUN is Mapped In 
(PROG now calls SUBR1) 
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When dynamic links that identify entrypoints in libraries already 
initialized are encountered, HlirOS needs to do much less work to make 
the connection. This is illustrated in Figure 3-11, in which the 
dynamic links to SRCH$$ and QiOe$A in SUBPl are snapped. 

Because SRai$$ is an entrypoint in PRIMDS, the process of snapping the 
faulted IP to it is again strai^tforward. FRIMDS is alrea<%7 present 
in the user's memory area, as always, and no initialization of any 
FRIMDS-resident subroutines is ever needed at runtime. 

Because ajOS$A is an entrypoint in a library EPF that has alreatJ^ been 
connected to the FROG program EPF, no initialization of the library EPF 
is needed. Even if a different entrypoint in the same library EPF, 
such as NLEN$A, had been called, no initialization would have been 
needed. 

As there are no longer any faulted IPs pointing to the DSfNT for SRCH$$, 
the DYNT in the illustration has been diaded in to indicate that it is 
no longer in use by that program invocation. :ihis diading does not 
represent any action by FRIMDS; the DSfNT still remains in the IROC 
segment as before. The shading is present only to indicate the absence 
of faulted IPs to the SRCH$$ DYNT. 
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Dynamic Links to SRCH$$ and CLOS$A in SUBRI Are Snapped 



MAIN PROG 

T 



EXT 



EXT 



I IP 
I IP 
I IP 
I IP 
I IP 
I IP 
I IP 
I IP 
I IP 
IP 
IP 
IP 
IP 



SUBRI . 
SUBR2 . 

CLOS$A 
SUBR2 . 
COMNl 
COMNg 

CLOS$A 
SPOOL$ 
COMNl 
C0MN2 
CLOSiA 



PRIMOS 




APPLICATION_LIBRARY 



After TSiird and Fourth Eynamic Links Are Snapped 

Figure 3-11 



3-27 



First Edition 



ADVANCED PROGPAMCR'S GUIOE, VCLUIG I: BIND AND EPFS 



Next, the faulted IP to SPOClIi$ in the SUBRl procedure is encountered, 
SHX3L$ is a Prime-suppLied entrypoint that comprises the program's 
interface to the Spooler subsystem. SPOQL$ is, at Rev. 19.4, supplied 
as a static-mode library. (Prime reserves the ri^t to change SIDQL$ 
to a library EPF in the future.) Figure 3-12 illustrates the FROG 
program EPF after snapping the ^namic link to SBXIj$. 

All static-mode libraries are placed in shared memory at systan 
coldstart. In this manner, they have a similarity to miVDS 
entrypoints. Linkage information for a static-mode library is 
initialized when a program invokes that static-mode library for the 
first time. Here, a similarity to program-class library EPFs exists. 
Because linkage information for a static-mode library is statically 
located, only one active copy may exist for each user process. This 
indicates a similarity to process-class library EPFs. 

In fact, once a program has invoked a static-mode library, ar^ other 
suspended programs for the same user process that have used the same 
static-mode library are made unrestartable by IRIMDS. Any attempt to 
continue the execution of a suspended program that has already used a 
reinitialized static-mode library is thwarted fcy ERIM3S, which displays 
an error message. (See Chapter 4.) 

As before, notice that the DZNT for SBOCL$ is new shaded, to indicate 
that the IKNT is no longer referenced by any faulted IPs in the EROG 
EPF. 

The SUBRl procedure now calls the SUBR2 procedure. 
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Dynamic Link to SPOOL$ In SUBR1 is Snapped 
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Finally, the last faulted IP, to the CLOS$A subroutine, is encxDuntered 
while executing procedure SUBR2. Figure 3-13 illustrates the ERCG 
program EPF after snapping this final faulted IP. 

As before, because the Application Library is alreac^ napped into 
manory and initialized, only Phases 7 through 9 of the EPF process are 
involved in snapping this faulted IP. Notice that the last DYNT, to 
CLOS$A, has been shaded in to indicate that no more faulted IPs 
pointing to the CLOS$A DYNT exist. 

Ihe final picture of the FROG program EPF shows a program in which all 
DYNTs, which are placeholders for subroutines, have been replaced by 
the actual subroutines, whether they reside in ERIMDS, in library EPFs, 
or in static-inode libraries. From this point forward, such an EPF 
executes faster when it encounters snapped IPs, because the (^namic 
linking mechanism is no longer involved. 

However, HlI^DS takes care to insure that these snapped IPs do not 
become a burden by preventing subsequent relocation of tiieir targets. 
An in-use library EPF, such as APELICATlDlUilBRARY in the example, 
cannot be ranoved via the PEMDVELEPF comirand; if a new version is 
installed, the user running the IRCG program EPF will not begin using 
the new version until after PRCG has completed and the next program 
calls the Application Library. If another program invokes 

APHjICATIDIUjIBRARY while PROG is suspended, FRIMDS will allocate and 
initialize a separate linkage area for tiie library EPF so that a 
separate connection is made. Tliis procedure preserves the integrity of 
the first connection made between IROG and APPLICATIDISUIjIBRARY, because 
that connection will continue to use the originally allocated linkage 
area for APPLICATIDliJilBRARY. 

FRIMDS has less control over static-mode libraries because they are 
less flexible. No new version of a static-mode library may be 
installed while users are running programs that use it, or programs may 
stop functioning correctly. Instead, the installer should shut down 
and coldstart PRIMDS when installing a new version of a static-mode 
library to ensure that programs are not adversely affected. 

If, while IROG is suspended, a static-mode library is reinitialized by 
another program's invocation of one of its entrypoints, IRIM3S detects 
this and flags EROG as being unrestartable. Iliis prevents PROG from 
later calling the static-mode library and inadvertently using the 
linkage data in that library that was left over from the other 
program's use of that library. 



Phase 9 - Termination 

A program EPF terminates just once per invocation, either by returning 
from its main entrypoint (preferred) or by calling EXIT (an alternate 
way of terminating) . 
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Dynamic Link to CLOS$A in SUBR2 is Snapped 
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A library EPF terminates sirtply hy returning from v^atever entrypoint 
invoked it. A library EPF typically is invoked many times during the 
life of a program, and it accordingly terminates, or returns, many 
times. Unlike a program EPF, there is no point at which a library EPF 
really finishes, because it is actually a collection of subroutines 
that service a program. 

Conceptually, a library EPF is part of the program that invokes it. 
When the program terminates, the library is also terminated by ERIMDS. 
However, JRIiyDS distinguishes between two types of library EPF in this 
regard: program-class and process-class library EPFs. When a program 
that invoked a program-class library EPF terminates, HIIMDS terminates 
the library EPF by marking for reinitialization the copy of its linkage 
area it earlier allocated and initialized for use by the library EPF in 
service of that particular program. 

Similarly, when a program EPF terminates, PRIMDS marks for 
reinitialization the linkage area used for that program invocation. 
When a linkage area is reinitialized, <Mily program data and faulted IPs 
are actually reinitialized, saving startup time. (Linkage areas for 
program EPFs and program-class library EPFs are deallocated when the 
command level they were invoked from is released. In addition, linkage 
areas for program EPFs are deallocated when they are removed from the 
EPF cache.) 

However, HIIMDS never reinitializes or deallocates the linkage area for 
a process-class library EPF when any program terminates, because that 
linkage area and the data it contains is usable for all programs 
invoked by that process. Only explicit removal (via RE^DVE_EPF) , 
logout (via LOGOUT) , or command envirorment initialization (via INI- 
TIAL IZEJCDMMAND_J1JVIR0NMENT) causes HlirDS to deallocate the linkage 
area associated with a process-class library EPF. 

For program EPFs and program-class library EPFs, keep in mind that only 
one copy of the linkage area for a terminated EPF is deallocated. 
Other copies may exist if the same program EPF is suspended within the 
same process or if another suspended program is also using the same 
program-class library EPF. ERIMDS ensures that suspended program 
invocations are not affected by the termination of other programs. 

FRIMDS also deallocates d/namically allocated memory (acquired via the 
ALLOCATE statonent in Hil/G, for example) v*en a program EPF or 
program-class library EPF terminates. FRIIVDS does not deallocate 
memory allocated by a process-class library EPF even when the 
REMDVE_EPP command is used to ratiove the EPF. Only the INITIALIZE_OOM- 
MAND__EN7IR0NMENT and LOGOUT commands deallocate memory dynamically 
allocated by process-class library EPFs. See Chapter 6 for more 
information on storage allocation and library EPFs. 
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Hiase 10 - Ranoval 

Once an EPF has completely terminated — that is, once it is no longer 
in use ty any suspended or executing program — IRIMDS may unmap the 
EPF from memory. The EPF$DEL subroutine performs this task. However, 
HilMDS typically keeps an EPF mapped for future use, depending upon the 
type of EPF involved. 

Removal of Program EPFs ; HlINDS usually places a terminated program 
EPF on the EPF cache rather than sinply unmapping it. While on the EPF 
cache, the EPF is still mapped to memory. If the EPF is invoked again 
while on the EPF cache, the mapping step (Phase 4) is avoided. In 
addition, if the iitpure areas (such as linkage data) have not been 
deallocated, the allocation st^ (Phase 5) is avoided, and only a 
subset of the initialization step (Phase 6) , reinitializing linkage 
information, is required. 

If, on the other hand, the EPF cache becomes unwiel(^, FRIMDS 
automatically unmaps the oldest EPF on the EPF cache, removing it fran 
the EPF cache at the same time, and deallocating its inpure areas. 

When you change command levels, HlI^DS removes all program EPFs frcm 
the EPF cache, deallocating their impure areas and unmapping than from 
manory. Only suspended (in-use) program EPFs and all library EPFs 
remain mapped to memory. (This behavior may change at future Revisions 
of PRIMDS.) 



Removal of Program-class Library EPFs ; When all programs that are 
using a program-class library EPF have terminated, the library EPF is 
itself considered terminated. However, PRIMDS leaves the EPF mapped to 
memory and also leaves its impure areas (such as linkage data) 
allocated. This allows faster scanning of the entrypoint table for 
that library EPF in the future. 

When you change command levels, ERI^DS deallocates all impure areas for 
program-class library EPFs that are not in use by a suspended or 
running program, but it leaves the library EPFs mapped to memory. 
(This bdiavior may change at future Revisions of PRI^DS.) 



Removal of Process-class Library EPFs ; When all programs that are 
using a process-class library EPF have terminated, the library EPF is 
itself considered terminated. However, FRIMDS leaves the EPF mapped to 
memory and also leaves its impure areas allocated because, once 
allocated and initialized, a process-class library EPF is considered 
initialized for the duration of that process (that is, until the user 
logs out or the command environment is reinitialized) . 

When not in use, you may remove a process-class library EPF with the 
REIOVE_E^ command. However, you can never remove an EPF that is in 
use (executing or suspended) . 
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Normally, you do not need to be concerned with the EPP cache or the 
maintaining of library EPFs perforrned fcy FRIMDS. These features are 
present as an optimization feature of ERIMDS. Biey do provide the 
ability to display useful information on a recently invoked EPF via the 
LIST_JI>F command without having to specify the -NOTL^IAPIED option. 

However, the maintaining of inactive EPFs in memory also may produce 
unexpected side effects. For example, while an EPF is mapped to memory 
for one or more users, installation of a new version of that EPF 
results in the generation of a .KPn file containing the old version, 
even though no user may be running the old version or may even have the 
old version suspended. The transparent nature of IRIIDS' creation of 
.Rfti files during COPY operations should keep this fran being a 
problem. 



Note 

An EPF cannot be deleted if another user either is running that 
EPF, has suspended that EPF, or has that EPF mapped to memory. 
Oi the other hand, if only one user is using an EPF, and the 
EPF is not running nor suspended (that is, it is a program EPF 
on the EPF cache or a library EPF still mapped to memory) , then 
that user can delete the EPF. Ihe EELETE command autanatically 
removes an inactive EPF if it is found to be in use during the 
first deletion attenpt; after removing the inactive EPF, it 
retries the deletion. 



A program that maps an EPF by calling EPF^lAP may also esqjlicitly call 
EPF$DEL to unmap that EPF. A program that calls EPF$RUN may make use 
of a special key that indicates that EPF$R[JN should call EPF^CEL after 
invoking the program EPF to unmap it rather than place it on the EPF 
cache. See Volume III of this series for more information on EPFSMAP, 
EPF$DEL, and EPF$RUN. 



HJW MOLTIPLE INVOQVTIDNS OF AN EPF ARE HANELED 

Sometimes a user mi^t invoke an EPF, either explicitly by running a 
program EPF or implicitly ty running a program that calls a library 
EPF, then suspend the EPF via Control-P, and issue a command that 
causes the same EPF to be reinvoked. Here, FRIMDS must allow the 
second invocation of the EPF to execute without disturbing the state of 
the first EPF, so that the user has the option of later continuing the 
first invocation. 

When ERIMDS detects that an EPF that is already mapped into memory is 
being invoked, FRIMDS checks the type of the EPF. If the EPF is a 
process-class library EPF, FRIMDS reuses the already-initialized 
linkage area for that EPF. For other types of EPFs, program EPFs and 
program-class library EPFs, IRItDS allocates new memory for the linkage 
areas of the EPF, rather than reusing any existing linkage areas for 
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the EPF. In this case, IRIM3S must initialize this newly allocated 
linkage infonnation. Because the stack is preserved when a program is 
suspended, and because PRIM3S does not destrc^ the linkage of the 
suspended EW, reinvoking the same EPF does not necessarily overwrite 
the data used by the suspended invocation. (See the restriction on 
using static-mode libraries, in Oiapter 4, for an exception to this 
rule.) 

However, to save time and manory, BRIMDS does reuse the same pure 
procedure (PROC) segments used by the first invocation of the EPF. 
HIIPDS can do this because segnents mapped in this manner cannot be 
modified, and because no data in PROC segnnents needs to be adjusted to 
reflect imaginary-to-actual msnory addresses. 



HOW SIMULTMEOUS USE OF AN EPF IS HflNELED 

When two or more users are running the same Elf, JRIM3S detects this 
and shares pure procedure (PROC) segments between the users. It can do 
this even when ore user's actual segment numbers for the EPF are 
different from another user's actual segnent numbers, because no 
segment numbers are stored in EROC segments. 

For example, if two users are running the same EPF at the same time, 
one user mi^t have imagirary rROC segment number +0 mapped into actual 
segment number 4365, while the other user mi^t have imaginary segment 
+0 of the same program EPF mapped into segnent number 4372, Segment 
4365 for the first user and segment 4372 for the second both map to the 
same imaginary FROC segnent in the file containing the EPF, reducing 
actual memory usage and paging overhead. 

To prevent one user from being able to adversely affect the smooth 
operation of another user's program, ^RI^DS protects PROC segments so 
that they cannot be written into when they are shared in this fashion. 



HOW DEBLGGING OF AN EPF IS HANCLED 

You can use EBG on a program EPF by issuing the EBG program command 
rather than the RESU^E program command. You cannot, however, use EBG 
to debug a library EM* directly. To debug a library EPF, link the 
ctoject files that comprise it into a program EPF innage with a main 
entrypoint consisting of a small module that invokes or otherwise 
declares the existence of all of the desired entypoints in the library 
EPF. Then, use the EBG program command to debug the resulting program 
EPF. 

EBG allows you to set breakpoints in the program EPF you are debugging, 
so EBG must be able to modify the pure procedure (PROC) segnents of the 
program. Yet rRIMDS normally maps the PROC segnents to their imaginary 
counterparts in the file containing the program EPF, setting the access 
to the EROC segnents so that they cannot be written into. Hew can EBG 
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set breakpoints in the code v^n it cannot write over any procecSure 
instructions? 

TO handle this, EBG specifically requests fRIMDS to not map mcc 
segments into memory. Instead, IRIMDS copies data from the imaginary 
IROC segnents in the progreni EPF file into the actual EROC segnents in 
monory. FRINDS sets the access on these copied PROC segnnents so that 
they can be written into. In addition, IRIfDS does not share these 
EROC segnents with any other users. 

Finally, if the user suspends EBG and invokes the program EPF he or she 
is debugging using the RESU^E comnand, FRIMDS allocates new IRCX: 
segments for this second invocation of the program EPF, preventing 
breakpoints set in EBG from affecting the RESUME invocation of the 
program EPF. When the RESU^E invocation has finished, the user may 
type START and continue debugging the EBG invocation of the program 
EPF. 

One of the effects of using EBG, therefore, is that attempts fcy the 
program EPF being debugged to modify itself generally go undetected. 
Such attempts cause access violation errors only when the program EPF 
is invoked using the RESUrE command. 



HOW RJNNING A RCTOTE EPF IS HANELED 

If a remote EPF is invoked, either fcy a user typing RESUME program 
where program . HJN resides on a remote system disk, or fcy an entrypomt 
search rule referencing a remote library EPF, HIIM3S does not map the 
PROC segnents to the remote file. Instead, the EROC segnents are 
copied from the file into memory before execution begins, in a fashion 
similar to the way IMHJRE segnents are handled. 

Tliis is done so that a running remote EPF will not be affected should 
the remote system or network be shut down. If the PROC segnents were 
mapped, then the effect on the running program of the remote system 
beoOTiing unavailable would be unpredictable. In any case, the 
condition could probably not be trapped hy the running program, because 
the code to handle such a condition would probably not be in physical 
memory. (The chances of error recovery code being frequently 
referenced tend to be small) . If the recovery code is not in physical 
memory, then it would have to be paged in from the remote system, with 
which contact had been lost. 

Therefore, due to the amojnt of time required to copy a large remote 
program EPF into memory, it is recommended that you provide local 
copies of EPFs on all systems in your network. By doing this, you take 
advantage of the faster memory mapping mechanism that is used for local 
EPFs. 
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EPFs and Static-mode 
Applications 



Because of the (^namic nature of EPFs, their interaction with existing 
static-mode applications is fraught with considerations and 
restrictions. In general, if you have a large body of software that is 
already built with SBG, it is best to designate one or two applications 
as pilot cases for conversion before committing to a wholesale 
conversion. Once you have succeeded at converting the chosen pilot 
applications, and have develc^d corresponding esq^ertise on conversion 
difficulties peculiar to your installation, you should then perform a 
wholesale conversion rather than a pieoaneal conversion, in order to 
avoid excessive concern over ttie considerations and restrictions 
described in this chapter. 

However, piecemeal conversion is seme times the only feasible approach, 
and, in such cases, you should thoroughly understand the information 
presented in this chapter before you begin, so that you knew what 
pitfalls may await you. 

In many cases, conversion involves simply relinking an application 
using BIND. However, certain uses of static systan-def ined data in 
static-mode programs may no longer function or may not be appropriate 
when these programs are converted to EPFs. 

Even if you do not intend to convert any applications to EPFs in the 
near future, you may have an existing application that requires 
modification to run on a Rev. 19.4 (or beyond) systan because of the 
existence of library Elfs that contain system library subroutines. 
Such an amplication is one that resides in shared memory and that 
' shares faulted IPs (Indirect Pointers) . 
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This chapter presentSr in detail, the considerations and restrictions 
involved in the interface bebweai the (^namic enviroiment provided ty 
EPFs and the older, static enviroiment still present in IRIMDS and in 
existing user-VTritten applications: 

• A restriction on the use of static-mode programs by EPFs 

• A restriction on the use of static-mode libraries by EPFs 

• Static information to avoid in EPFs 

• The effect of EPFs on existing shared static-mode applications 

RESTRICT]DN CN IRE USE OF STATIC-M3ia: IR0GRAM5 BY EPFS 

Because the monory used ty static-mode programs is all statically 
allocated, restrictions are placed on their use. 

When This Restriction Is Apparent 

The effect of this restriction is seen when one static-mode program is 
suspended, another static-mode program is invoked, and then an attempt 
is made to continue execution of the first static-mode program. 
Because both static-mode programs use the same areas of memory, FRIMDS 
prevents the attempt to continue execution of the first static-mode 
program after the second static-mode program has executed. 

A Sample of This Restriction 

For example, ED and SLIST are both static-mode progrems. (They may be 
converted to EPFs in the future, at which point you must substitute two 
other static-mode programs for the example below.) If a user invokes 
ED, suspends the program via Control-P, and then invokes SLIST, the act 
of loading SLIST into manory causes the suspended memory image of ED to 
be at least partially destroyed. 

Because users typically use Control-P to abort a running program rather 
than to suspend it with the intention of continuing the suspended 
program later, JRircs allows the subsequent invocation of SLIST, 



First Edition 4-2 



EPFS MD STATIC-MDDE APPLICATIONS 



If, after ocanpleting the SLIST session, the user attanpts to use the 
START command to continue the suspended ED session, ERI^DS rejects the 
attempt, as seen here: 



ED 

INHJT 

Jill - I am worried that Tom's Tasty Tinsel micjit not be 
able to handle our shiianent of 200 stainless steel pizzas, 
I've eaten there, and I have noticed their receiving dock 
is not really set up for such large itans. Seeing as you're 
in charge of all this, I suggest you call than up and 
make sure they know v?hat they're getting 1 — Fred 

P.S. The order number is (user types Control-P) 

QUIT. 

OK 14:19:48 0.218 0.033 level 2 

SLIST FREDDY>TOMS_ORDER# 

Fred: the order number for Tan' s Tasty Tinsel order of 

200 stainless steel pizzas is 0214453. — Sue 

OK 14:19:53 0.172 0.054 level 2+ 

PFT.EASEJLEyEL 

Static mode program released, (rls) 

OK 14:20:01 0.054 0.000 level 2 

START 

Attempt to proceed to overwritten program image, (listen.) 

ER 14:20:02 0.045 0.000 level 2 



How to Recover From Encountering the Restriction 

If you encounter this restriction, you should release the command stack 
using the RELEASEJ^EVEL -ALL command. In addition, you ^ould use the 
CLOSE -ALL command to close any file units opened ty the restricted 
invocation. 

An alternative method of recovery is to issue the INITIALIZE_O0M- 
MftND_JNVIRCNMENT command (abbreviated ICE) . 

A more general solution to this problan is to convert your existing 
static-^node programs to program EPFs. 



Note 

These recovery methods recover the user's ability to execute 
commands up to the full limit of the user's enviroraient. They 
do not recover the data in the overwritten program. In the 
example given above, for instance, the edit session is lost. 
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A General Statement of the Restriction 

A generalization of this restriction is that only one static-mode 
prograan may be active, whether suspended or running, at any given time 
for a given process. 

Therefore, if the user invokes program A, then quits and invokes 
program B, then quits and invokes program C, and so on, ERIMDS will 
autonatically terminate active static-mode programs in the sequence (A, 
B, C, and so on) each time a new static-mode program is invoked. Any 
subsequent attanpt to continue an iractive static-mode program that had 
been suspended causes ERIM3S to issue an error message. 



The Reason Behind the Restriction 

As iirplied ty the error message displayed when the restriction is 
encountered, FRIMDS prevents an attanpt to continue a suspended program 
invocation if it detects that parts of the suspended program image may 
have been overwritten. 

Unlike program EPFs, the placement of procedure and linkage areas for 
static-mode programs is determined during program load sessions by 
either the SEG/IDAD utilities or by the progrannmer during the SBG/LQAD 
session. Static-mode programs therefore cannot be dynamically placed 
in memory vAien they are invoked. 

Additionally, most static-mode programs create their own stack bases 
rather than using the command stack (used by program EPFs) . The 
placement of this stack base is also determined when the program is 
loaded. 



Due to these characteristics, static-mode programs cannot coexist 
memory for a particular user process. 



xn 



RESTRICTION ON THE USE OF STATIC-M3DE LIBRARIES BY EPFS 

Because the linkage areas for static-mode libraries are all statically 
allocated, a restriction is placed on their use by program EPFs. 



When This Restriction Is Apparent 

The effect of this restriction is seai when one prograri EPF is 
suspended, another program EPF is invoked, and then an attanpt is made 
to continue execution of the first program EPF. If both the first and 
second program EPF use the same static-mode library, then IRI^DS 
prevents the attempt to continue execution of the first program EPF 
after the second program EPF has executed. 
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A Sample of This Restriction 

In this exarapae, a program EPF named SKO^JIYJ^EPORrS, which makes use 
of the static-mode library SHX3L$, is invoked, suspended via Control-P, 
and then reinvoked. When the second invocation completes, the user 
attonpts to proceed with the first invocation, and encounters the 
static-mode library restriction. (The Prime-suppLied SK)CIi$ library 
may be converted to a library EPF in the future. At that point, if 
other static-mode libraries still exist, you must substitute the use of 
one of them and a program that uses it in the example belcw to 
reproduce it. However, it is possible that all static-mode libraries 
supEiied by Prims may be converted to library EPFs in the future, at 
which point the restriction under discussion is no longer pertinent.) 



OK, RDY -DGMG 

OK 10:13:30 0.060 0.000 

RES^^E SPOQLcJCCREPORIS 

GO 

Enter start date for report spooling, or <CR> to leave: 

— > 08/10/84 

Enter end date for report spooling, or <CR> to leave: 

— > 08/14/84 

Spooling reports for period starting on 08/10/84 and ending on 
08/14/84... 

08/10/84 is ERTOOS (12 records) 

08/11/84 is PRT006 (13 records) 

08/12/84 is PRT007 (10 records) 

08/13/84 is IRPOOS (5 records) 

08/14/84 is PRTOIO (47 records) 

Enter start date for report spooling, or <CR> to leave: 

— > (user types Control-P) 

QUIT, 

OK 10:20:46 12.254 9.301 level 2 

RESUME SPOOLAjyEU^EPORIS 

GO 

Enter start date for report spooling, or <CR> to leave: 

— > 08/17/84 

Enter end date for report spooling, or <CR> to leave: 

— > 08/21/84 

Spooling reports for period starting on 08/17/84 and ending on 
08/21/84... 

08/17/84 is rKr012 (8 records) 

08/18/84 is PRT013 (10 records) 

08/19/84 is PRT015 (25 records) 

08/20/84 is H?r016 (18 records) 

08/21/84 is IRr017 (30 records) 
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Enter start date for report spooling, or <CR> to leave: 

— > (CR) 

OK 10:27:31 10.205 7.722 level 2 

START /* User new attempts to continue first invocation. 

Attempt to proceed to overwritten program image, (listen_) 

ER 10:27:52 0.060 0.000 level 2 



Hew to Recover From Encountering the Restriction 

If you encounter this restriction, you should release the command stack 
using the RELEASEJiEVEL -ALL command. In addition, you should use the 
CLOSE -ALL command to close any file units opened fcy the restricted 
invocation. 

An alternative method of recovery is to issue the INITIAL IZE_O0M- 
MRND_ENVIRaWENT command (al±»reviated ICE) . 



The Reason Bdiind the Restriction 

As iirplied fcy the error message displayed when the restriction is 
encountered, FRI^DS prevents an attempt to continue a suspended program 
invocation if it detects that parts of the suspended program image may 
have been overwritten. 

Although the program in the example is a suspended program EPF, and 
therefore has not had any of its program image overwritten, the 
static-mode library SKX)L$, used ty the EPF, has had its linka^ area 
overwritten. 

When a static-mode library is first invoked ty a program EPF, H^I^DS 
initializes the linkage area for the library. During ejsecution of the 
static-mode library subroutines, the linkage area for the static-mode 
library is used and modified ty the static-mode subroutines. 

If execution of the program EPF is suspended, for example, via 
Control-P, a subsequent command that runs a program EPF or a 
static-mode program that also uses the same static-mode library may 
occur. If this happens, ERIM)S must reinitialize the linkage area for 
the static-mode library v4ien the library is called, so that the new 
program will not use subroutines that are derating on undefined data 
values in the linkage area. 

Because the linkage area for a static-mode library is statically 
located, it cannot be relocated fcy IRI^DS for the new program that is 
calling the library. 

Therefore, reinitializing the linkage area for that library destrc^s 
the previous contents of the linkage area. The previous contoits of 
the linkage area were set during the first invocation of the library hy 
the original program EEF. 
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FRIM3S detects this condition and prevents the user from continuing 
under such circumstances so that the original program EPF will not 
behave in an undefined fashion when it makes subsequent calls to the 
static-mode library. 



STATIC INPORmTIDN TO AVOID IN EPFS 

Whether building a new application as an EH* or converting an existing 
application to an EPF, you should avoid the use of certain static 
information by the program. Such static information includes: 

• Conmand line information 

• Error information 

Static cOTimand line information is accessed and manipulated using the 
subroutines GOMANL and RDrK$$; static error information is accessed 
and manipulated using the subroutines GETERR, mERR, and ERRSET. An 
EPF that uses these subroutines may sometimes operate correctly and, at 
other times, produce invalid results. 



Static Coromand Line Information 

The CDMANL and RnrK$$ subroutines have been modified at Rev. 19.4 so 
that static oranmand line information, which prior to Rev. 19.4 was 
per-process information, is now maintained for each command level. 
Tliis allows separate programs that use these subroutines to coexist in 
the same process without disturbing eadi other. Hcwever, if one 
program that uses CX)MANL and RnrK$$ directly invokes another progran 
that also uses these subroutines, the second program' s use of these 
subroutines will disrupt the comnand line information for the first 
program, and invalid results may be produced. (One progran directly 
invoking another does not produce a change in the user's command level; 
static command line information is maintained for eadi command level, 
but not for each individual parogram.) 

The alternative to using OOMANL and RnrK$$ is to design programs so 
that they accept the command line from the PRIMDS command processor as 
an argument to the min entrypoint of the program, and so that they 
parse the command line using a parsing subroutine sudi as ai$PIX or 

ac>L$A. 
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Static Error Information 

The GETERR, PRERR, and EEU^SET subroutines have not been modified at 
Rev. 19.4. The static error vector remains a per-process entity. 
Therefore, two programs that use EI?RSET along with GETEEIR and PRERR to 
set and retrieve static error information are likely to have adverse 
effects on each other if they coexist in the same process as EPFs. 

The alternative to using these subroutines is to use FRIMDS subroutines 
that return error codes rather than older versions that set the static 
error vector; to use the ERRFR$ subroutine to display error messages; 
and to pass the returned error codes back to the calling subroutines or 
the PRirOS command processor via the second argument of the main 
entrypoint calling sequence. 



EFFECT OF EPFS ON EXISTING SHARED APPLICATIONS 

In rare cases, existing applications that use shared segments for 
storage of program code (as opposed to ^ared data) may be adversely 
affected by the introduction of library EPFs at Rev. 19.4. In 
particular, shared static-mode programs and libraries that place 
faulted IPs (Indirect Pointers) in shared segments will probably 
ejdiibit erratic behavior when run on a Rev, 19.4 systan. (Faulted IPs 
are IPs to external subroutines that are satisfied with dynamic links, 
or rnnsiTs, during the loading of the application.) 

Applications that renain static-mode at Rev. 19,4 should not encounter 
problems when run under Rev. 19.4 PRI^DS if they do not share faulted 
IPs, J^lications that do share faulted IPs, either e}^licitly or 
inplicitly (by sharing linkage frames) may be affected at Rev, 19.4 
because libraries, which before Rev. 19.4 were statically assigned 
segments during system coldstart, may at Rev. 19.4 be library EPFs. 
Therefore, a particular entrypoint in a library EPF may have one 
address for user A and another address for user B, even though the 
library EPF is shared by the EPF mechanism. Prior to Rev. 19.4, that 
entrypoint would always have the same address for all users f ollcwing a 
system coldstart. 

Shared applications that place sane or all of their linkage information 
in shared memory (segnents '2000 through '3777) are likely to encounter 
this situation, because linkage information typically contains faulted 
IPs for most subroutines. /plications that ej^licitly place any 
faulted IPs in procedure text that is then shared will also encounter 
this situation. 

Normally, all IPs and ECBs are placed in the linkage frame for a 
procedure; linkage areas for a program are normally placed in per-user 
(nondiared) memory. Sate applications place ECBs in the procedure 
frame by using the -PBECB option of the compiler or by specifying the 
ECB peeudo-op of PMA within a PROC block, rather than within a LINK 
block, in a EMA program. Such applications will encounter no 
difficulties unless they are converted to EPFs. 
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Other aj^lications jxLace the linkage frame of one or more procedures in 
the i^ared (procedure) segments. Faulted IPs may be present in the 
linkage frenies of such applications. If this is the case, the shared 
segments are not protected against modification, allowing these faulted 
IPs to be snapped as the application is used. (A segnent-protection 
value of 700 octal causes the SHARE command to allow all users to 
modi^ the segment.) Such applications will likely behave erratically 
until they are modified so that they do not share linkage frames. 

Rarely, applications explicitly place faulted IPs in shared segments. 
These IPs are explicitly resolved during system coldstart by a program 
that snaps all of the links for that program before protecting the 
shared segments against further modification. (Applications that ^are 
faulted IPs and e35)licitly snap them during coldstart are unusual and 
are not built according to Prime-documented guidelines.) Such 
applications will probably behave erratically until they are modified 
so that they do not ^are faulted IPs. 

All of the practices described in the preceding paragraphs are used to 
reduce the working set of an application. By sharing BCBs, IPs, 
linkage frames, or all three, less total memory is used when several 
users run the application. 



Effect of Sharing Faulted IPs 

An IP that points to the ECB (Entry Control Block) of a procedure 
starts out as a faulted IP if it points to a dynamically linked object 
(an entrypoint that is accessed via the ^namic linking mechanism) . 
When an indirect reference occurs through a faulted IP, typically via a 
PCL IP,* instruction, FRIMDS determines the name of the entrypoint 
being targeted by the IP. ERI^DS then searches its list of entrypoint 
names, starting with internal entrypoints, then moving on to items in 
the user's entrypoint search rule (ENTRY$,SR) . 

When FRIPDS finds the desired entrypoint, IRIMDS determines the address 
of the ECB of the target procedure and then replaces the original IP 
with that address. 

As part of finding the desired entrypoint, HRIPDS may map in a new 
library EPF, assigning it areas of manory in which it is to reside. 
Therefore, a reference by user A to subroutine PLOTXy through a faulted 
IP mi^t be resolved by ERIMDS to an ECB at location 4362/1764, whereas 
the same reference ty user B to the same subroutine mi^t be resolved 
to another copy of the ECB, for the same subroutine, at location 
4357 A764. 

For IPs placed in per-user (nondiared) memory segnents, this poses no 
problem, because each user has a separate copy of the IP to match the 
separate copy of the ECB. 
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However, a program sharing faulted IPs resolves them at s^^stam 
coldstart so that they point to the ECBs of desired entrypoints. 
Library EPFs containing desired entrypoints are mapped in for the user 
who first shares the program {typically user 1, which runs the systan 
startup file) . Addresses of the desired entrypoints within the library 
EPFs replace the original faulted IPs as the effective addresses of the 
ECBs, 

Then, when another user invokes the same application later, the same 
resolved IPs are used (because they reside in shared segnents) . 
However, libraries are mapped into memory only as a result of 
encountering faulted IPs; therefore, the library EPFs referenced by 
these resolved IPs will probably not be mapped into memory for this 
second user. 

Even if the needed library EPFs are mapped into memory for the user, 
they may not necessarily reside in the corresponding areas of memory as 
they did for user 1 when the faulted IPs were snapped. 

As a result, the application typically encounters an illegal segnent 
error, an access violation error, or a pointer fault error. 



Modifying an /plication to Not Share Faulted IPs 

To modify an application so that it does not share faulted IPs, you 
must either change its load sequence so that shared segments are used 
to contain only procedure code and other constant data, or you must 
load all of the subroutines it needs into the same application, 
including those in Prime-supplied libraries. 



Modifying the Load Sequence ; Modifying the load sequence of an 
application so that it does not share IPs is the safest approach. It 
involves changing the load sequence so that only pure code (procedure 
code) is placed in shared segnents and disabling special-purpose 
programs that snap faulted IPs at ooldstart for the application. For 
example, a CPL parogram that builds such an ap>plication (via SEG) mic^t 
contain the following line: 



S/LQAD MDDULEl 2035 2035 



The underlined segnent number, the second 2035 in the oorarrand line, 
specifies that linkage information (including IPs and the ECB) is to be 
placed in segnent '2035, a shared segnent. Modify this line, and lines 
like it, to place the linkage information in nonshared segnents, such 
as segment '4000. For example: 



S/LOAD MDDULEl 2035 4000 
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TJien, modify the load sequence for your application so that it performs 
no processing of the .SBG file, program map, or object files for the 
purposes of gathering information on the locations of faulted IPs. 
(Because Prime provides no program for doing this, an example of this 
cannot be documented here; it is e:qpected that each develcpnent group 
that has built an amplication that shares IPs has also built its own 
tools to find faulted IPs. ) An application may have no such program, 
if it leaves shared segments unprotected against user modification. 

Finally, find the portion of the system startup file, PRIMDS.CDMI {or 
C_mMD) , that shares the application and modify it so that it no longer 
runs a program to snap faulted IPs in the shared segment images of the 
program. If your application has no such program, modify the systan 
startup file to set the protection for shared segments to '600 (read 
and execute) rather than '700 (read, write, and execute). 



Loading In All Subroutines ; An alternate solution is to load in all 
subroutines used ^ your application that do not reside in PRIMDS 
itself or in static-mode (Prime-supplied) libraries; that is, load all 
subroutines used by your application that reside in library EPFs 
directly into your application in place of the dynamic links it 
currently loads. 

This solution has the disadvantage of increasing the size of your 
application while duplicating the extra subroutines loaded; other 
applications will be unable to access the copies of those subroutines 
loaded into your application, and will instead use the copies in the 
library EE^s. Hcwever, as the size of your application generally 
affects only the ooldstart initialization time of your application, 
performance should not be reduced; in fact, because the remaining 
faulted IPs can still be snapped at coldstart, the performance gains 
realized by constructing your application in this unusual way can be 
maintained, (Internal ERIfOS subroutines and subroutines in 
static-mode libraries remain in the same areas of memory for all users 
after system coldstart.) 

However, you must load in the unshared versions of all libraries that 
your application references. For example, in a particular application 
that uses the Pascal library, the load sequence mi^t contain: 



D/LIBPARY PASLIB 
D/LIBRARY 
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Replace these statonents to load in the unbared versions of the 
libraries. The default libraries loaded in via a LIBRARY ooiratand with 
no filename are SPLLIBr PFTNIB, and lETNIB; the undiared versions are 
NSHiLIB and NMTULB. (IPINIB has no unshared counterpart; it is 
included in NPFTNIB.) The corresponding statanents for the above 
sample section of a load sequence would therefore read: 



D/LIBRARY NEASLIB 
dAibrary NSPLLIB 
DA-IBRARY NPPTNIB 
D/LIBRARY 



Note that the D/LIBPARY command, with no filename, is still given at 
the end; it results in the loading of D5?Nrs to static entrypoints 
(entrypoints into HIIMDS and entrypoints residing in static-mode 
libraries) . 
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■fliis chapter describes hew to design and iirplement programs as program 
EPFs. 



WHAT IS A EROGRRM EPF? 

A program EPF is an executable file system object. A program EPF is 
generated by you, the programmer, using BIND. It may be used fcy you, 
by another user, or by another program. 

To a programmer, a program EPF is a file containing a program. To a 
user, a program EPF is a command. To a program, a program EPF is a 
subroutine with a predefined calling sequence accessible via one of 
three PRIM3S subroutines: CP$, EPF$RUN, or EPF$INVK. 



The Programmer's View of a Program EPF 

Typically, a program EPF contains a completed and working program. A 
programmer builds a program EPF fcy follcwing three steps: 

1. Entering the program into the i^stem using an editor such as 
EMACS 

2. Compiling the program using a compiler such as F77 or PLl/G, or 
assembling the program using EMA 
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3, Binding the program using BIND 

Step 1, entering the program into the system, produces source files for 
the compiler or assembler. Step 2, compiling or assembling the 
progrcm, uses the source files to produce object files. Step 3, 
binding the program, uses the object files to produce a program EPF. 

Tlie file containing a program EPF has the name program . BUN. The .HJN 
suffix specifies that the file contains a program EPF. (An alternate 
suffix for an EPF file, .RRi, is described in Chapter 1.) 

Iliis chapter describes how to take full advantage of program EPFs 
during each of the above steps. 



The User's View of a Program EPF 

A user runs a program EPF in one of two ways: 

• By typing the name of the program EPF as a HRINDS command 

• By using the ERI^DS RESUME command to run the program EPF 

General information on entering commands and running programs is 
provided for users in the Prime User's Guide . 

Typically, if you write a program, you provide additional documentation 
describing the nature and purpose of the ^ogram, where it resides, how 
to run it, and whom to contact if problems arise. 



Invoking a Program EPF as a ERirPS Command ; If a program EPF resides 
in the directory CMDNCO on the command disk of the system, users invoke 
the program EPF by simply typing its name as if it were a normal ERIMDS 
command. The conmand disk is usually logical disk on a system. For 
more information, see your System Administrator or the Systgn 
Administrator's Guide . 

Invoking a Program EPF Using the RESU1\E Conmand ; A user invokes any 
program EPF by using the PRI^DS RESU^E command and specifying the 
pathname of the program EPF. The user must have Read access to the 
program EPF. 



The Program's View of a Program EPF 

A program invokes a program EPF by calling one of several system 
subroutines, depending on the needs of the invoking program. When one 
program invokes another program in this manner, the first program is 
suspended while the second program runs. When the second program 
finishes, the first program continues running. 
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■Hie first program nay supply input data to the second program when it 
invokes the second program. It can also accept returned information 
from the second progrcm when the second program finishes. For example, 
the first program can receive information from the second program as to 
whether or not the second progrcm ran successfully. 

Ihe ability for one program to call another is not limited to one 
occurrence; the second progrcm can call a third, and the third can 
call a fourth. The only limits placed on the invocation of prograns 
from within programs are: 

• Resource limits, such as amount of memory and internal table 
space 

• Restrictions placed on the use of static-mode programs (those 
prograns linked using SEG or LOAD rather than BIND) 

• Limits set by the System Administrator on the command level 
breadth 

The resource limits are exceeded when HRIM3S is unable to allocate 
resources to execute another program EPF. A discussion of static-mode 
program restrictions is found in Chapter 4. 

The command level breadth is the number of programs that are active at 
a given command level. ERIMDS maintains this number; this number is 
when the user is at FRIMDS command level. When the user runs a program 
EPF, ERIFDS sets this number to 1. If the program EPF invokes another 
program EPF, IRIMDS then sets this number to 2. If the second program 
EPF invokes a third, ERIICS sets this number to 3, because three 
programs are active at that command level. 

As program EPFs fini^ and return to their callers, PRIM3S decrements 
this number. When the original program EPF is reached, FRIMDS sets 
this number to 1. The original program EPF may then choose to invoke 
further program EPFs, which causes ERIM3S to again increase the command 
level breadth. However, v*en the original program EPF finally 
finishes, PRIMDS returns this number to 0, and places the user at 
PRIMDS command level. 

The System Administrator has the ability to limit the command level 
breadth for all users of the system on a per-user basis. Therefore, an 
attempt by a progran EPF to invoke another program EPF may be thwarted 
ty ERIM3S because the maximum limit on the user's command level breadth 
would be exceeded. 

For more information on invoking programs from within programs, see 
Volume III of this series. 
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WRITING THE MAIN PROGRAM OF A HROGRAM EPF 

In every program EPF, one procedure is defined as the main entrypoint. 
The nain procedure is the procedure that is called ty ERIM3S when the 
program EPF is run. It is identified during the BIND session via the 
MAIN subcommand. If the MAIN subcommand is not issued, BIND assumes 
the first procedure linked is the main procedure. 

The main procedure of a program EPF should accept no arguments unless 
command line processing is to occur. See Volume III of this series for 
information on writing program EPFs that perform ooraraand line 
processing. 

Therefore, the main procedure of an F77 program ^ould begin as 
follows: 



PROGRAM program-name 
The main procedure of an ETO program should begin with : 

SUBROUTINE program-name 

The main procedure of a PLl/G program should begin with : 

program-name: PROCEDURE; 

The main procedure of a EMA program should be structured as described 
in Qiapter 7. However, its ECB should specify that it accepts no 
arguments, as follcws: 

program-eci) ECB program-name-start 

In addition, the END pseudo instruction at the end of the module should 
specify the ECB that is to serve as the main entrypoint for the module, 
as follows: 

END program-ecto 

If you specify no label following the END pseudo instruction, you must 
use the MAIN subcommand of BIND when you link the IMA module as the 
first module of a program EPF, or the program will fail to run. 
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The MIN Subcommand of BIND 

Use the MAIN subcommand of BIND to specify the main entrypoint of the 
program EPF. PRIMDS invokes this entrypoint when the EPF is invoked. 
If the MAIN subcommand is not specified during the linking of a program 
EPF, BIND defaults to choosing the first ECB linked during the BIND 
session as the main entrypoint. 

The main entrypoint of a program EPF has a predefined calling sequence 
if it accepts arguments. "Hiis calling sequence is described in detail 
in Volume III of this series. 



The DYNT Subcommand of BIND 

The DyNT subcommand of BIND controls the production of c^namic links, 
typically for references to external entrypoints defined in your cwn 
personal library. (PRIfDS does not support cfynamic linking to common 
areas. ) 

You may use the DXNT subcommand to declare specific entrypoint names as 
dynamic links, using the form: 



DYNT name-1 [name-2 ...] 



The DYNT subcommand is useful when no library object (.BIN) file exists 
to define dynamic links for entrypoints in a library EPF, such as a 
library EPF you have created for your own personal use. 

You should use the DYOT subcommand only for entrypoints in a library 
EPF that is for your own personal use. Any library supplied to you, or 
that you sujply to other users, should be accompanied ty an object file 
that contains the appropriate DYNTs. This library should be fcuilt 
according to the guidelines shown in Chapter 6 and should be kept in a 
single, system-wide location. Users of this library should always use 
the LIBRARY or LOAD subcommand to link the library object file at BIND 
time; they should not use the DYOT subcommand to produce links to 
individual entrypoints within the library. 



5-5 First Edition 



6 



Library EPFs 



Library EPFs provide a simple and direc± way to build and maintain a 
library of ooiranonly used subroutines for one or more products. Use of 
library EPFs can be simple, yet flexible enough to meet the demands of 
different applications. Sophisticated use of library EPFs is possible, 
but it requires sophisticated knowledge of how your product is 
organized. 

To make the use of library EPFs as simple as possible, FRIM3S provides 
sane intriguing mechanisms that help make the existence of library EPFs 
transparent to most users. These mechanisms include: 

• Library search lists 

• Autonatic dynamic linking 

• On-<femand library EPF mapping 

As the programmer of a library EPF, you must be aware of how these 
mechanisms are seen by users, and how to use them during the 
developnent process for your product library. 

To fully acquaint you with all aspects of library EPFs, this chapter: 

• Describes what a library EPF is 

• Describes the steps needed to create a library EPF 

• Examines the choice of the appropriate type of library EPF in 
detail 
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• Explains how to use EBG on a library EPF 

• Describes library entrypoint seardi lists and how to manipulate 
than 

• Describes specific aspects of the EPF medianism that pertain to 
library EPPs 



WHAT IS A LIBRARY EPF? 

A library EPF is an executable file system object. A library EPF is 
generated by you, the programmer, using BIND. It is used ty other 
programs that invoke it by calling entrypoints in it. 

TO a programmer, a library EPF is a file containing a program. To a 
program, a library EPF is a collection of subroutines. 



The Programmer ' s View of a Library EPF 

T/pically, a library EET" contains a collection of completed and working 
subroutines program. There are two kinds of library EPF: 

• Program-class 

• Process-class 

The choice as to whether a library EPF should be program-class or 
process-class is up to the programmer who is building the library EPF. 
Typically, a library EPF is built as a program-class library EPF; 
PRIMDS treats a program-class library EPF as part of any program that 
uses that library EPF. Occasionally, a library EPF is best fcuilt as a 
process-class library EPF; FRI^DS keeps process-class library EPFs 
separate f ran program invocations. 

A programmer builds a library EPF by following these steps: 

1. Enter the subroutines into the system using an editor such as 
EMACS or ED. 

2. Compile the subroutines entered in Step 1 using a compiler 
such as F77 or PLl/G, or assemble the subroutines using PMA. 

3. Determine how the library is to be organized. 

4. Determine which subroutines in the library are to be 
considered entrypoints into the library, and ensure that there 
are no naming conflicts between your entrypoints and 
entrypoints in other libraries. 
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5. Link the subroutines cx>mpiled in Step 2 into one cm: two 
library EPFs using BIND, indicating whidi subroutines are 
entrypoints. 

6. Build a EMA file listing entrypoints as dynamic links (DYNTs). 

7. Assemble the PMA file built in Step 6, generating an object 
(.BIN) file containing D5fNTs to your library, 

8. Use EEB to make the .BIN file generated in Step 7 a 
non- force-linked library. 

9. Install the .BIN file built in Step 8 in the appropriate 
directory. 

10. Install the library EPF built in Step 5 in tiie appropriate 
directory, 

11. Modify the appropriate entrypoint search list to reference the 
library EH" installed in Step 10. 

Step 1, entering the subroutines into the system, produces source files 
for the compiler or assembler. Step 2, compiling or assembling the 
subroutines, uses the source files to produce object files. Step 3, 
determining how the library is to be organized, requires you to assess 
the way in which individual subroutines in your library need to be 
initialized when invoked. Step 4, determining the entrypoints for your 
library, requires you to check your oitrypoint names against a 
Prime-supplied list of reserved entrypoint names (provided later in 
this chapter) and against other library EPFs, not provided by Prime, 
used at your installation. 

Step 5, linking the subroutines using BIND, uses the object files to 
produce a library EPF. The file containing a library EPF has the name 
library . ELfN. The ,HJN suffix specifies that the file contains an EPF. 
(An alternate suffix for an EPF file, .RRi, is described in Chapter 1.) 

Steps 6 through 9 provide the file to be loaded or linked ty progress 
that are to use your library. They use the LOAD or LIBRARY subcommand 
of either SBG or BIND, specifying the .BIN file installed in Step 9, to 
resolve references to subroutines in your library to dynamic links 
(DYNTs) . 

Steps 10 and 11 make your library EPF available to whoever uses an 
entrypoint search list that specifies your library EPF. Running 
programs that encounter dynamic links specifying subroutines that are 
entrypoints in your library EPF are autonatically connected to your 
library EPF. Such programs acquire this ability ty loading or linking 
the library (.BIN) file installed in Step 9 if the entrypoint seardi 
list names your library EPF. 

This chapter describes how to take full advantage of library EPFs 
.during eac±i of the above steps. 
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The Program's View of a Library EPF 

To a program, a library EPF is invoked by calling a subroutine that is 
an entrypoint to that library EPF. Unlike the main entrypoint of a 
progran EPF, PRI^DS imposes no constraints upon the calling sequence of 
the subroutine. 



STEPS IN BUILDING A LIBRfiRY EPF 

This section describes the steps performed in building a library EPF. 
Seme of the steps require even further detailed explanation for certain 
cases; subsequent sections in this chapter address these needs. 

It is iiip)rtant that you read the descriptions of all of the steps 
before you begin designing and coding your library EPF. In particular, 
the entrypoint-naming issues described in Step 4 may impact your design 
specif icatiions. 



Step 1 - Enter the Subroutines 

You enter the subroutines for a library ECT" just as you would for a 
program EPF, ty using a tejct editor such as EMflCS or ED. No 
subroutines i^ould be coded as PROGRAM modules ; they ^ould all be 
SUBROUTINE, IROCEDURE, or HJNCTIDN modules. No restrictions are placed 
on their calling sequences by IRIMDS. 



St:ep 2 - Conpile tjie Subroutines 

You compile or assemble the subroutines for a library EPF using one of 
Prime's compilers or IMA. The compiler must generate 64V-mode or 
321-roode code; a PMA program must contain the pseudo-op SBG or SEGR. 
These requirements are described in Chapter 7. 



Step 3 - Determine How the Library Is to be Organized 

You now consider whether the library should be a single program-class 
library EPF, a single process-class library EPF, or one of each. 
Typically, program-class library EPFs are the best choice, 
Ocxasionally, however, it iiiproves performance to put subroutines in a 
process-class library EPF, as long as they will perform correctly. See 
the section below, entitled CHO0SIN3 THE RIGHT TYPE OF LIBRflRY EPF , for 
detailed information on making the decision between building a single 
program-class library EPF, a single process-class library EPF, or two 
library EPFs (one of each type) . 
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Ihe simplest, and often the most appropriate, decision is to build one 
program-class library EPF. Only in rare cases does this approach not 
produce a working library. Advantages of process-class library EPFs 
are primarily in terms of performance. 



Step 4 - Determine Library Entrypoints 

You now build a list of the subroutines that are to be considered 
entrypoints in your library. You will use this list for two purposes: 

• To identify entrypoints in the library EPF during the BIND 
session 

• To identify external entrypoint rrferences as dynamic links in 
programs that use your library EET 

Subroutines that are not made entrypoints to a library EPF cannot be 
called ty subroutines outside that library EPF, unless their addresses 
are provided by other entrypoints in the library EPF via ENTRY VflRIflBLE 
(or similar) functionality. 

Prime reserves many names for its own use as entrypoint names. These 
names are listed next. 



Reserved Names 

The canpLete list of entrypoint names reserved by ERIMDS is on the 
following page. In addition to the names in this list, names 
containing a $ symbol are reserved ty HlirOS and Prime-suppLied 
libraries. 



VSmHHG 

Do not attempt to use any of the entrypoints listed unless 
other documentaidon specifically ejqjlains it. Using 
undocumented PRI^DS subroutine entrypoints may result in 
unusual behavior fcy PRIMDS subsystans. In addition, such 
subroutines nay be removed or changed at any point without 
warning. 



Note 

Prime guarantees that no new rames will be added to the 
following list. In other words, no reserved names will be 
added to this list? the only changes made to this list will be 
the removal of names that are used only internally by Prime 
products as the names are changed to have $ syiriDols in them. 
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ACKRCr 


mCRYP 


LIBTBL 


QPOST 


TLIB 


ADDjQRBC 


EPF_ERR 


LIST_3BL 


QunnD 


TlIN 


ADOCRD 


EPtLJ^j 


LN3CMP 


QUOTEL 


TLOB 


ADQRBC 


ERASE 


LOCK 


ROBASE 


TIOJ 


ADRESS 


ERROPN 


LOGJVEN 


R3FALT 


TBIiRFD 


AD_CMD 


ERRRIN 


LGG_PM1() 


RDASC 


TIDEC 


ATinc 


ERRSHIT 


MCSDAT 


REBIN 


TIHEX 


APPEND 


EVA[t_A 


MCb-lDD 


RDNERG 


TIMaAT 


ATROOD 


EXIT 


M3VB 


REPRCN 


TIMIBC 


ATLIST 


EXIRAC 


M3VE 


RECYCL 


TIMSLT 


AOMAIN 


FTT.ERR 


IDVtU 


RFTGRP 


TEXT 


Ki'LUN 


FILHER 


M3VWDS 


REMANS 


TPQ270 


AVATT. 


FiNure 


M3GCTL 


REMJSR 


TMDISP 


BCKDIB 


FIND_U 


NETCHK 


REPOST 


INOU 


BSCMAN 


FiND_UID 


NETFIG 


RESTART. 


INCXJA 


aiN 


FNDRBC 


NETFRC 


RGb'i'RY 


IDDEC 


CMiPC_ 


FWDWRD 


NET5ET 


RJEBG 


TOHEX 


CFI 


PORCEW 


NEWS 


RJMNIT 


'ilJNL 


CiKLCG 


FREELDES 


NOmST 


RJIROC 


ixjocr 


CKINST 


FREEJUl 


NPXPRC 


RMLOCK 


TRNRCV 


aCNENM 


FSCHOC 


NXTLIN 


RPTSPL 


•n^TYIE 


a.RARS 


GAT.T.KS 


QAUSER 


RQUEST 


1RVEHS3D 


CLREAD 


GCHAR 


OERRm 


Rfa'WiL 


TSATRC 


CLRLIN 


GRTADR 


OIWDFL 


SALJIP 


'itsTAMP 


CLUJLDS 


GETEOT 


OFNDOC 


SCANB 


UETERY 


CLSDOC 


GE-i'ERR 


OPNQFL 


SCHAR 


UDTFO? 


aCLPOST 


GETNPG 


CWL2 


SEiiRCIi_C 


UNLANJE 


CMD_J!RE_ 


GETOYB 


PI IB 


SEAROLH 


UNLOCK 


CNIN 


GE-JREG 


PI IN 


SBCBLD 


UNPACKJi 


GOMANL 


GE'iaLT 


PlOB 


SBGOON 


UPCRSE 


GONTRL 


GETJIEPL 


PlOU 


SELANG 


UH1ATE_S 


CRAWIi. 


GFILKS 


P2UPCS 


SETA37P 


USERTD 


CRFITFD 


GINFO 


PACK3IT 


SEONAM 


USRmM 


lATtLA 


qosum: 


PACK_CHA 


SEIREC 


VMM9G 


DCTEXS 


GOREAD 


PACK_IMr 


SET_SRL 


VMM9G2 


DECRJiOP 


GTDOCR 


PARSJOT* 


SET_VERS 


VMBG3 


DEFILE 


CTWORD 


PARTCL 


SFRJTSC 


VREMID 


DELAX- 


GUSLKS 


EASSWD 


SFRJIP 


WHATrr 


DELASL 


HASH_U 


PCREAT 


SHRLIB 


WRASC 


DRI,h?i'E 


HASIl_UID 


PEXIT 


SIl_CMD 


WRBIN 


eeletejQ 


ICMrB_ 


PFIL2A 


SLAVE 


WRITLINE 


DRTDAS 


ICPl,_ 


PFLM9E 


Sr.AVER 


WKl'PG 


m3270 


ICS2Cr 


m\VG 


SCUR3_ 


XLACPP 


DIDNUM 


ID 


PINIT 


SPLC3IK 


XLASGN 


DIRSKK 


INCPi'K 


PINLNK 


SiMBEC 


XLCLR 


DISPLA 


INITPI 


PK2LDV 


snuEX 


XLQ.RA 


EMIDRS 


INITJJPX 


PRIBLD 


yi'PNC 


XLGONN 


EMLCP 


inhljQ-S 


miCCM 


SERBL 


XLGGON 


IMJMID 


INTOL 


H?VSB_ 


SIRTPH 


XLGWC 


DOSSUB 


IQNET 


Pi'KAP 


STOFF 


XLUASN 


DPTINI 


IQUSER 


HJTBL 


SUBMIT 


XMTRCV 


DPTOFF 


ISFEPF 


PUTBLT 


SWJ?«K_ 




ERAINJ3U 


JUS'IRT 


HJTLHOP 


SWFlfL 




EM3270 


LCKGHP 


QPRRSE 


SWINTQ 




First Edition 




6-6 







LIBRARY EPFS 



Step 5 - Linking the Subroutines 

You now link the subroutines using BIND to create a library EPF of the 
appropriate type, or to create two library EPFs, one of each type. 

For a program-class library EPF, the link sequence is: 



BIND library-EET'-f ilename 
LIBMDDE -PROGRAM 
LOAD module-l 
LOAD moclule-2 



ENTRYNATE name-1 [name-2 ...] 

LIBRARY [special-library-1 ...] /* if needed 

LIBRARY 

RESCLVELPEFERRn)_a)MM)N 

MAP [map-filename] [options] 

FILE 



For a process-class library EPF, the link sequence is: 



BIND library-EPF-filename 
LIBMDDE -PROCESS 
LOAD module-1 
LOAD module-2 



EMTRYNAME name-1 [name-2 ...] 

LIBRARY [special-library-1 ..,] /* if needed 

LIBRARY H10CESS_CLASS 

LIBRARY 

RESCLVELDEEERRH)_OOMMDN 

MAP [map-filename] [options] 

FILE 



The differences betweai linking a progran-class library EPF and a 
process-class library EPF are: 

• Use of the LIBMDIX: -IROCESS subcommand rather than LIBMDIS: 
-HIOGRAM 

• Use of the LIBRARY EROCESS_CLASS subcommand iimediately before 
the LIBRARY subcommand 
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The LIBMDra; sub(X)ininand specifies the type of library EPF to be 
generated. The LIBRflRY PRC)CESS_CLASS subcommand links a library that 
causes c^namic allocation performed ty your library EPF to be done from 
process-class, rather than program-class, memory. 

Although not required to link a library EPF, the 

RESQLVELDEFERE?ED_(DMIDN and MAP suboomraands are reoomraended for use 
when debugging a library EPF. See also the section below entitled HCW 
TO USE DBG ON A LIBRARY EPF. 



An Easy Way to Declare Entrypoints ; An easier way to declare 
entrypoints to your library EPF is to use the ENTRYNA^E -ALL and 
ENTOYNAME -NCX^E subcommands. Between use of these two subcommands, 
BIND autanatically makes any subroutines linked via the LOAD or LIBRARY 
subconmands into entrypoints for the library. 

Therefore, the template you would use for the aj^opriate section of 
the above two build file templates is: 



ENTRYNATE -ALL 

LOAD entrypoint-module-1 

LClAD entrypoint-module-2 



ENIRYNAME -NDNE 

LOAD other-module-1 /* if needed 

LOAD other-module-2 



LIBRARY [special-library-1 ...] /* if needed 



Make certain that you issue an EMIRYNAIE -NCM) subcommand before using 
the LIBRARY subcommand. Otherwise, you are likely to produce a library 
EPF that either will not execute correctly or that has entrypoint names 
that conflict with Prime-sujplied libraries. 



Step 6 - Building a EMA Entrypoint File 

You now build a single IMA file that declares all of the entrypoints to 
your library EPF (or both library EE^s) as (tynamic links. This file 
has the format: 



* List of dynamic links for MYLIBRARY.RUN. 
SBG 
SYML 
DYNT entrypoint-1 
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WD 

SEG 

SWL 

DYNT entrypoint-2 

END 



An easy way to build this file is to enter the entrypoint names into a 
file named EMRYPOINTS, one name per line. For example: 



INIT_J.INE 

GETLCHAR 

NEMLCHARJXDRJlilNE 

CLEARJLINE 

BACKSEAaUilNE 

EMLIilNE 



Now, enter and run the following CPL file to build a file named 
EMIRYIOINTS.PMA: 



&DATA ED 

LOAD ENIRYIOINTS 

TOP 

N;IB SEG : SYML;N;GM 1/ DYNT /Fl/ : END/;* 

FILE ENTRYIOINTS.PMA 

SEND 



This produces the following ENTRYPOIMES.iWA file when run on the 
ENTRYEOINTS file built in the earlier example: 



SEG 


: S^ML 




DYNT 


INIT_JiINE 


: END 


SEG 


s SYML 




DYNT 


GETLCEJAR : 


END 


SEG 


: SYML 




DYNT 


NEW_CHARJDRJ.INE : END 


SEG 


: SYML 




DYNT 


OiEARJilNE 


: END 


SEG 


: SYML 




DYNT 


BACKSPACE_JLINE : END 


SEG 


: SYML 




DYNT END_JiINE : 


END 
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Step 7 - Assemble the Entrypoints File 

You new assemble the entrypoints file ty issuing the command! 

mh ENIRYroiNlS -LISTIN3 ND 



This produces a file named EOTRYIOIins.BIN. (You usually do not need 
to produce a listing of the file. If you wish to produce a listing, 
emit the -LISTING NO specification.) For example: 



OK, PMA ENTRYPOINTS -LISTING W 
0000 ERRORS (PMA Rev. 19.4) 
OK, 



Step 8 - Use EEB to Generate Library File 

You now use EEB, the Binary Editor, to generate a new version of the 
ENTRYPOINTS.BIN file that does not forcibly load or link itself into 
whatever prograro is using it. A GIL program to perform this step is: 



&DATA EEB ENTRYPOINTS.BIN MYLIBRARY.BIN 
RFL 

COPY ALL 
SFL 

Qurr 

&END 



You now have a file named MHiIBRARY.BIN that can be installed as the 
library file that programs can load or link to use your library EPF. 

For example, if you named the CPL file shown above FIX_LIB.CRi, and ran 
it on the ErnRYPOINTS.BIN file produced in the earlier sample PMA 
invocation, the follcwing output would result: 



OK, RESUME FI^UjTB 






fEFB rev 19.4] 






tWi'ER, RFL 






USiTKR, COPY ALL 






INITJliINE 




GEILCHMl 


NEW_CHARJDRJiINE 




CLEARJiilNE 


BACKSHVCEJjINE 




ENDJLINE 


.Bai'iUM. 






tNTER, SFL 






tNl'ER, QUIT 






OK, 
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Notice how the entrypoint names are listed, two per line. 
See Chapter 10 for more inf conation on EEB. 

Step 9 - Install the Library File 

You new install the library file, ramed MHjIBRfiRY.BIN in the above 
example, into the appropriate directory. For systam-^de libraries, 
the LIB uro is appropriate. For example: 

COPY MYLIBRARY.BIN LIB>MXLIBRfiRy.BIN -NDjQUERY -dM -REPORP 

When a library is installed in UFD LIB, progrsms can load (SBG) or link 
(BIND) it by issuing the SBG or BIND subcommand: 

LIBRARY library-filename 

In the example used, the LIBRARY MYLIBRARY subcommand would be used. 

Alternatively, you may widi to place the library file in a directory 
common to users in your project. In this case, programs must specify 
the full pathname OS. the library file when loading or linking it. Ohey 
may use either the LOAD or LIBRARY subcommand of SBG or BIND with a 
full pathname, although the LIBRARY subcommand is recommended because 
its name communicates more clearly to someone reading the program's 
build file what the purpose of the file is. 



Step 10 - Install the Library EPF 

You now install the library EPF file built in Step 5. As with Step 9, 
you may install the library EPF in either a systan-wide directory or in 
a directory common to users who are to use it. Ihe systan-wide library 
directory for library EPFs is the LIBRARIES* UFD. For example: 



COPY MXLIBRARY.RUN LIBRARIES*>MyLIBRARY.HJN -ND_QUERY -Um -REPORP 



Whether installed in the system-wide LIBRARIES* UFD or in another 
directory, the library EPF is not usable until the next step, when its 
full pathname is added to the entrypoint search list of users that are 
to make use of the library EPF or of programs that use the library EPF. 
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Step 11 - Modify the Entrypoint Search List 

You now modify the appropriate entrypoint seardi list so that the 
library EPF you installed in Step 10 is accessible ty the appropriate 
users. 

If you have installed the library EPF in the system-wide LIBRARIES* 
UFD, then you typically modify the system-wide default entrypoint 
search list, SYSTEM>ENTIIY$.SR. The following sample session inserts 
the search rule LIBRfiRIES*>MXLIBRARy.EDN at the bottan of the 
SYSTEM>EMIRY$.SR search list: 



OK, ED SYSTEM>EKr[RY$.SR 

EDIT 

BOTTOM 

INSERT LIBRARIES*>MYL]BRfiRY.HJN 

FILE 

SYSTEM>ENTRY$ . SR 

OK, 



Caution 

Typically, you do not have access to SYSTEM>ENTRY$.SR unless 
you are the System Administrator. If you modify it, it is 
possible that you mi^t unknowingly render it unusable, such as 
ty putting one search rule in twice (a duplicate rule) . If 
this happens, not only will users be affected, but a subsequent 
coldstart of the system may render the supervisor termiral 
nearly ineffective. In such a situation, you will be unable to 
use editor ED to fix the file, as ED references faulted IPs to 
call system subroutines via the dynamic linking mechanism. 

The solution to this problem is to use the nondiiared editor, 
NSED, rather than the shared editor ED, to fix the default 
search list file. NSED runs under IRIMDS II, and therefore 
does not ever reference faulted IPs. 



Alternatively, you may modify the entrypoint search list of the users 
who are to use the library EPF, or ask them to make the modifications 
themselves. If these users are using the system-wide default 
entrypoint search list, then you must construct an entrypoint searcih 
list for them that includes both the system-wide default search list 
and your own library EPF. 
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For example, if the users all have access to a directcary named 
ERQJECTLAf in which you have already installed the library EPF (and 
possibly the library file named MXLIBRfiRY.BIN) , you might type: 



OK, m 

INHJT 

-SYSTEM 

FRQJBCTLA>MniIBRfiRY. HJN 

MI 
EDIT 

FILE HlQJBCT_J^Et7nRY$.SR 

OK, 

After you do this, all users who are to use this library must pLaoe a 
SETJSEHICELJDLES command in their I/DGIN.CHj or LOGIN.aOMI file, as 
follows: 



SETjSEAROiJULES IIRaJBCP_J\>ENTRY$ 



Note 

Whether you modify the system-wide default entrypoint search 
list SYSTEM>ENTRY$,SR, modify sane other aitrypoint searcJi 
list, or create a new search list, users who are alreac^ logged 
in must issue the SET_3EfiRaoUIiES ooraraand before they can run 
a program that uses your library EPF, (A user who has the 
appropriate SET-SENlOLJlJIiES command in his or her LOGIN. CPL 
file may simply issue the iNrriALEE-COMTMrojENVmCMIENT 
oOTimand, as may all users if you have modified the system-wide 
default entrypoint search list.) If a user complains that a 
LINKAGEU'ADLT$ condition was signaled indicating a failure to 
link to an entrypoint in your library EPF, it may be that the 
user is not using an entrypoint search list that includes your 
library EPF. Ask the user to issue the LIST-SEARCHJ^JLES 
command (abbreviated LSR) and ensure that your library EPF is 
listed therein. 

If the user has the correct entrypoint search list, then use 
the LI5T_LIBRARYJNIRYP0INTS command (abbreviated LLENT) to 
ensure that the desired subroutine is in fact an entrypoint in 
your library EPF. See the section below, entitled EXAMININ3 
aWRYPOINT LISTS, for more information on this OOTimand. 
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CH00SIN3 THE RIGHT T£PE OF LIBRARY EPF 

A library EPF must be either a program-class or process-class library 
EPF, as described earlier in this Qiapter. TMs section escplains how 
you determine the appropriate classification for subroutines in your 
library EM". 

Ohe decision as to whetiier a library EPF is process-class or 
program-class is actually made on a per-subroutine basis, and includes 
such factors as: 

• How the subroutine uses its linkage area 

• How procedures external to the subroutine are classified 

In general, the sinplest decision is to put all of your subroutines 
into a program-class library EPF. In most cases, this will produce a 
working library EPF, although the performance of the library EM* may 
not be as good as if a process-class library EPF were used. 

Performance for a process-class library EPF is often better than that 
of the same subroutines collected as a program-class library EPF 
because the linkage area for the library EET" need not be reallocated 
and reinitialized each time a progran using the library EPF is run. 

However, subroutines in a process-class library EPF must observe 
certain restrictions on their use of linkage areas and other external 
procedures. Tliese restrictions are: 

• A subroutine in a process-class library EPF may not call a 
procedure in a program-class library EPF or a static-mode 
library. 

• Because of the above restriction, a subroutine in a 
process-class library EPF may not perform any language-directed 
I/O operations. (No FRIMDS-resident subroutine ever performs 
language-directed I/O operations; rather, the subroutines that 
are called upon to perform language-directed I/O operations call 
roiMDS-resident subroutines to accomplish their tasks.) 

• A subroutine in a process-class library EPF should not modify 
any data in its linkage area, except in certain special cases. 

Both restrictions can be difficult to check for in a given subroutine. 
miMDS does detect and prevent a violation of the restriction against a 
process-class library EPF subroutine invoking a program-class library 
EPF or static-mode procedure. However, IRIM3S cannot detect a 
potaitially invalid use of data in the linkage area. 

The remainder of this section describes the st^s used to determine 
whether you want one library EPF of a particular class, or two library 
EPFs (one of each class) . 
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In summary, these steps are: 

1. Determine the class requironents of each subroutine in your 
library. 

2. Determine the class requirements of your library EPF using the 
subroutine requiraonents data. 

If your library EPF must meet performance constraints, then the first 
requirement can become somewhat complicated. Process-class subroutines 
tend to have better performance than program-class subroutines because 
they tend to require compLete initialization of their linkage areas 
less often, but they must meet more stringent requironents (such as not 
being able to call a program-class subroutine) . 

First, you determine whidi subroutines must be program-class 
subroutines based on two absolute rules listed belcw. 

Second, you examine the remaining subroutines, and determine which of 
those should be program-class subroutines based on their use of static 
data. 

Ohird, you consider specific cases where the usage of static data by a 

subroutine iitplies that it must be in the program class, tut in fact 

the nature of the static data it uses allows it to be in the process 
class. 

Finally, you consider specific cases where the usage of static data ty 
a subroutine indicates a need to redesign the subroutine (and probably 
its external interface) so that it can be in the process class. 



Determining the Class Requirements of a Subroutine 

It is most desirable for a subroutine to work properly as a 
process-class subroutine. Process-class subroutines do not incur the 
overhead of allocating and initializing their linkage areas each time 
they are invoked by a new program. 

Instead, their linkage areas are allocated and initialized only the 
first time the process-class library EPF to which tiiey belong is mapped 
into memory, and remain valid until the same process-class library EPF 
is unmaH»d from memory. If a program that uses that process-class 
library EPF is run several times between the mapping of the library EPF 
and its unmapping, the linkage will still be allocated and initialized 
only once. 

However, due to the restrictions described above, not all subroutines 
will work when built into a process-class library EPF. For the most 
pirt, all subroutines will work when built into program-class library 
EPFS, which do incur linkage allocation and initialization overhead for 
each program invocation. 
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•Hie follcwing sections are designed to help you determine, for each 
subroutine, whether it must be a program-class subroutine or can be in 
either class. 

This section is split up into several rules. Some of these rules are 
absolute rules that cannot be violated. Other rules apply to most 
subroutines, but exceptional cases are listed or described. 

Subsequent sections discuss ways in which a subroutine can be examined 
in greater detail to determine if it is, or can be made, a 
process-class subroutine. 

Rule 1 - Restriction on Library Qass Mixing ; It is an absolute rule 
that a processr-class library EPF subroutine cannot call a subroutine 
within a program-class library EPF or a static-mode library. If this 
is attempted, IRIIDS will produce an error message similar to the 
following: 

Error: condition "LINKfiGE_ERRDR$" raised at 4342(3) A2506. 
Attempt to link to program class library EPF entrypoint "ATTEEV" 
from a process class EPF. 
ER! 



It is possible fca: a process-class subroutine to call some other 
subroutine that then calls a program-class or static-mode library 
subroutine. However, in most cases, this cannot be done because tiiis 
rule must be reapplied. 

Specifically, if process-class subroutine A calls subroutine B which 
calls program-class (or static-mode library) subroutine C, then 
subroutine B cannot be a process-class subroutine, or Rule 1 would be 
violated. In addition, subroutine B cannot be a program-class or 
static-mode subroutine, or again. Rule 1 would be violated when 
subroutine A calls subroutine B. 

This situation will be valid only if subroutine B is part of a program 
EPF or a static-mode program. FRIMDS will treat the invocation of 
subroutine C by subroutine B as being a program-to-program invocation, 
and will allow it, since FRIMDS will be able to properly allocate and 
initialize the linkage area for the program-class library EPF or 
static-mode library containing subroutine C. 

However, subroutine A cannot call subroutine B if it is not part of a 
library unless the entrypoint f car subroutine B is passed to subroutine 
A as part of its calling sequence or through a common area. (For 
example, a PLl/G ENTRY VARIABLE declaration provides this 
functionality. ) 

Therefore, under most circumstances, caice a process-class library 
subroutine is invoked, only process-class subroutines or IRIMDS direct 
entry subroutines can be called until tiie process-class library 
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subroutine retxirns to its caller. Exceptions to this statement occur 
only v*ien non-library subroutine calls occur during this period. 
(Ncxi-library subroutine calls can also occur as a result of a condition 
being signaled. See the Subroutines Reference Guide for information on 
writing condition handlers.) 

Rule 2 - Restriction on Use of Language I/O ; If a subroutine makes use 
of language-directed I/O, it must be made a program-class subroutine. 
Language-directed I/O includes statanents such as READ, WRITE, ENGOra:, 
DEOOEG, and OHW in PORIRAN, HJT, GET, OFEN, O/DSE in PLl/G. 

■niis rule is, in fact, a corollary to Rule 1. All Prime-supplied 
languages generate subroutine calls to perform lan^age-directed I/O, 
All such languages provide their runtime support of langaage I/O as 
program-class library EPFs. To permit correct management of data 
buffers between program invocations, language I/O library EPFs must be 
program-class. 

Rule 3 - Problem When Storing Data in Linkage Areas ; A subroutine that 
uses its linkage area (static storage) to stcnre data will probably not 
function correctly if built into a process-class library EPF. 

Exceptions occur for faulted IPs that are resolved fcy the miVOS 
dynamic linking mechanism and for imaginary IPs that are converted to 
actual IPs by the FRIM3S EE^ invcxation raechanisra. Such IPs are 
autanatically generated by all Prime-suppiied langaages, including PMA. 
However, PMA progranmers may e:?>licitly specify an IP in their linkage 
text that is covered by this exception only if the subroutine never 
attempts to modify the contents of the IP. 

Other special-case subroutines, such as random number generators, may 
be considered exceptions to this rule. This is discussed later in this 
chapter. 



Determining the Use of Static Data by a Subroutine 

If your product does not have stringent performance criteria to meet, 
it is recommended that you not devote time attempting to determine 
which subroutines are process-class and program-class. At this point, 
if you don't know whether scxne of your subroutines require piaoement in 
a prograort-class library EHF, you should assume that they do. 

However, if your produc± does have performance standards to meet, it 
may be worthwhile to invest the time needed to determine precisely 
which subroutines can and cannot be safely made process-class 
subroutines. It is even conceivable that redesigning the internal 
operation (and perhaps external interface) of a few chosen subroutines 
so that they may execute as process-class subroutines would be a 
reasorable investment of your time, if the resulting performance 
increase justifies it. 
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The key issue that determines whether a subroutine must run as a 
program-class subroutine involves its use of data in the linkage area. 
This includes: 

• Static data (declared as STATIC in PLl/G, with DATA statement in 
EDRTEIAN, and, in PMA, via LINK pseudo instruction followed by 
DATA, OCT, lEC, BSS, BSZ, BCB, IP, and SO on) 

• Conmon data (declared as STATIC EXTEia^AL in PLl/G, with OOMMDN 
statement in PORIRAN, via COMM and EXT pseudo instructions in 
FMA) 

The reason the linkage area is the crux of the issue is that the 
linkage area is not reallocated and reinitialized for a process-class 
library EPF when a new program calls a member subroutine. Therefore, 
if any of the data in the linkage area for the library is 
program-related, the execution of the second progrem that calls the 
process-class library EPF after it is mapped into memory may produce 
inaccurate results or cause error conditions. See Chapter 5 for more 
information on such restrictions. 

If a subroutine st cares data in the linkage area, and it uses that data 
at any other point, then the subroutine is probably not reentrant. A 
non-reentrant subroutine must typically be put in a program-class 
library EPF, to prevent it fran misbehaving after multiple invocations 
ty separate programs. 

Here is a sample PLl/G subroutine that is not reoitrant: 



average : prcx; (number ) returns ( fixed bin (15 ) ) ; 

del nimiber fixed bin (15) ; /* The newest number. */ 

del count fixed bin (15) static init(O), /* # of numbers, */ 
total fixed bin (31) static init(O); /* Total value. */ 

count=count+l ; /* Another number. */ 
total=total+number ; /* Total it up. */ 

return (divide (total, count, 15)); /* Return quotient of average. */ 
end; /* average: proc */ 
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This subroutine is meant to be called in the following wa/: 



(3o_average: proc; 

del current_avg fixed bin (15), 
next_pumber fixed bin (15); 

dca tnou entry (char (80), fixed bin(15)), 
tidec entry (fixed bin(15)), 
tovfd$ entry (fixed bin(15)), 
tnoua entry (char (80), fixed bin(15)), 
average entry (fixed bin (15)) returns (fixed bin(15)); 

call tnou ('Enter numbers. Type to stop. ',31); 
current_avg=0 ; 
next_jiuraber=-l ; 

do while (next_number''=0) ; 

call tnoua ('Enter next number: ',19); 

call tidec (next_number); 

if next^jTumber^^O then current_avg=average(nextjiumber) ; 

end; 

call tnoua (• Hie average is ',15); 
call tovfd$ (currait_avg) ; 
call tnou(",0); 

end; 

The AVEEWGE subroutine uses STATIC INTT for its averaging data, so that 
the data values are maintained betweoi calls to the AVERAGE subroutine. 
It modifies the STATIC INIT storage during execution. This makes it 
nonreaitrant even within a given program. That is, even within one 
program, the AVEIWGE subroutine can be used to calculate the average of 
only one stream of numbers at a time. 

In fact, as it currently exists, it can handle only one stream of 
numbers for ons entire program execution, because there is no method to 
reinitialize the STATIC INIT data. Evai if an alternate entrypoint 
existed to do this, the subroutine would still be able to manage only 
one stream of numbers at a time. 

Hie single-stream restriction on the AVEI^flGE subroutine is not a 
problem if the calling program needs to calculate an average for only a 
single stream of numbers at a time. However, it does require tiiat if 
AVERAGE is itade part of a library EPF, it must be a program-class 
library EPF. That way, separate linkage is allocated and initialized 
for each different program that uses the AVERAGE subroutine. 

If program A uses AVERAGE, and program B is then run and it also uses 

. AVERAGE, the fact that AVERAGE is in a program-class library will 

prevent program B from siirply oontinuing the calculation of average 
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number values established in program A, Instead, program B will start 
with a fresh copy of the averaging data. 



When Nonreentrant Subroutines Should Be Process-class 

There are certain cases where a nonreoitrant subroutine, as determined 
fcy its use of static storage, should actually be in a process-class 
library EPF, Generally, a subroutine that uses static data to store 
and use only process-related information, ratiier than program-related 
information, may be a nonreentrant subroutine that can be installed in 
a process-class library EPF. 

Process-related information includes such data as: username, user 
number, user's terminal type, the name of the i^stan, today's date, 
limits on the user's use of ooranand level depth and breadth and on the 
number ot static and dynamic segments, user's project id, and so on. 
Tliis information is generally process-related or system-related, rather 
than program-related. Typically, it does not change during the life of 
a process, and hence does not need to be reinitialized each time a new 
program calls a library EPF subroutine that maintains this type of 
information. 

However, carefully consider whether the use of a process-related datum 
is in itself process-related or program-related. For example, today's 
date is usually process-related, but it may be important for a program 
to acquire an up-to-date value, instead of a value that may have been 
put into the linkage area sane time ago, including (possibly) 
yesterday. 

For a more tangible example of a subroutine that is nonreentrant, but 
uses only process-related data in the linkage area, consider the 
following PLl/G subroutine: 



get_username: proc returns(char(32)); 

del 1 timdat_info static, 
2 date char (6) , 
2 time fixed bin (15), 
2 ticks fixed bin (15), 
2 meters (4) fixed bin(15) , 
2 tps fixed bin (15) , 
2 user_jiumber fixed bin(15), 
2 user_pame char (32); 

del have_info bit(l) static init('O'b); 

del timdat entry(l,2 char (6) ,2 fixed bin(15),2 fixed bin(15), 
2 (4) fixed bin(15),2 fixed bin(15),2 fixed bin(15), 
2 char (32), fixed bin(15)); 
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if ''have_info 
then do; 

call tiitKaat(tim[3at_infOr28) ; 

have_inf op= ' 1 ' b ; 

end; 

return (user_jTanie) ; 
end; 



This subroutine returns the usemame of the current user. It incurs 
the added overhead of calling the systan TIVDAT subroutine only \ihen it 
is first invoked. 

Even though GETJUSERNAME uses static stcarage in a nonreentrant fashion, 
you can see that because all of its static storage identifies 
process-wide data (the user name) , it can be in a process-class library 
EPF. It will be more efficient there than in a program-class library 
ERF. 



Converting a Nonreaitrant Subroutine to be Reentrant 

If the performance of a particular group of program-class subroutines 
needs to be increased, it is possible that converting them to 
process-class subroutines will help result in the needed performance 
inprovements. 

To do this, you must convert the subroutine or group of subroutines to 
a reentrant entity. This often requires major internal changes, 
probably a t&trite of the target modules, possibly even rewriting into 
a different language. For example, ELl/G handles the smooth 
construction of reentrant subroutines quite well, due to its ability to 
handle pointer manipulation and based structure declaration. 

If Hil/G cannot be used, PMA is an alternative. Here, the XB register 
is often substituted for references to static data in the linkage area 
that were once IB relative. 

In any case, such a conversion often requires changes in the external 
appearance of the target modules. All uses of the target modules may 
have to be changed to accommodate the new calling sequences of the 
target modules. For this reason, it is recommended that you design new 
interfaces to allow full reoitrancy, both inside and outside a single 
program. 



SimpJ.e Conversion ; To understand hew to convert a target module, we'll 
look at the AVERAGE subroutine, shown earlier. A simple conversion 
would be to move the small amount of static data out of the linkage 
area by making it part of the calling sequence of the subroutine. 
•Initialization of this data would then be left to the calling program. 
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"Hie resulting version of AVERAGE would appear thus: 



average: proc (number, count, total) returns (fixed bin (15)) ; 

del number fi:ffid bin (15), /* The newest number. */ 
count fixed bin(15), /* # of numbers. */ 
total fixed bin (31) ; /* Total value. */ 

oount=oount+l ; /* Another number, */ 
total=total+number ; /* Total it up. */ 

return(divide(total,oount,15)) ; /* Return quotient of average. */ 
end; /* average: proc */ 



Because the calling sequence of the subroutine has been changed, the 
method of calling the subroutine would have to be adjusted for all 
users of the subroutine, as indicated in the following example: 



do_average: proc; 

del current_avg fixed bin (15), 
avgjiumber fixed bin (15) , 
avg_total fixed bin (31), 
next_number fixed bin (15) ; 

del tnou entry (char (80), fixed bin(15)), 
tidec entry (fixed bin(15)), 
tovfd$ entry (fixed bin(15)), 
tnoua entry (char (80), fixed bin(15)), 
average entry (fixed bin (15) , fixed bin (15), fixed bin (31)) 
returns (fixed bin(15)); 

call tnouCEnter numbers. T^pe to stop. ',31); 
cur r ent_avg^ ; 
avg_number=0 ; 
avg_total=0 ; 
next_number=-l ; 

do while (next_number'^=0); 

call tnoua ('Enter next number: ',19); 

call tidec (next_number) ; 

if next_number''=0 then current_avg=average(next_number, 

avg_nuraber , avg_total ) ; 
end; 

call tnoua (' Hie average is ',15); 
call tovfd$ (current_avg) ; 
call tnou(",0); 

end; 
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As a result of these changes, the AVERAGE subroutine can become a 
process-class subroutine. In addition, the calling program can use it 
for averaging one stream of numbers at a time. The calling program may 
use several copies of AVQJtOBER and AVa.TOTAL to keep the number 
streams separate. 

However, this is a limited form of coping with the nonreentrancy 
problem for two reasons: 

• It requires all calling programs to perform the initialization 
that is best performed hy the target module 

• To replace large amounts of static data, long (expensive) 
calling sequences would be needed 

A General ^^roach to Conversion ; A more general approach is to 
separate out the AVEKVSE subroutine into three separate procedures. 
One procedure, INIT_AVERAGE, allocates storage for and initializes the 
data for a specific number stream. The second procedure, DQJCTERAGE, 
actually performs the computation. The third procedure, END_AVERfiGE, 
is called to indicate the end of the calling program' s need for the 
maintenance of data on a particular number stream, and hence 
deallocates the storage for that stream. 

To make use of the efficient way in which the Prime 50 Series machines 
manipulate pointers, the identifier for a number stream will be a 
pointer. The INHLAVERAGE, when invoked, returns a pointer to be used 
to identify that particular number stream to DO_AVEE»GE and 
END_J57ERAGE. Bie same pointer identifies the area in memory in which 
the number stream data is stored, for use by DQJWERAGE, and which is 
to be freed by EUDJS/ERAGE. Now, the AVEE»GE module appears as 
follows: 



init_avg: proc returns (ptr ) ; 

del avg_id ptr; 

del 1 average_streani based (avg_id) , 

2 count fixed bin(15), /* # of numbers. */ 
2 total fixed bin (31); /* Total value. */ 

allocate average_stream set(avg_id); 

count=0; 

total=0; 

return (avg_id) ; 

end; /* init_avg: proc */ 

average: proc (avg_id, number) returns (fixed bin (15)) ; 

del avg_id ptr, /* Points to average data structure. */ 
number fixed bin(15); /* The newest number. */ 
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del 1 aver age_str earn based (avg_id), 

2 count fibred bin (15) , /* # of numbers. */ 
2 total fixed bin (31) ; /* Total value. */ 

c»unt=oount+l; /* Another number. */ 
total=total+number ; /* Total it up. */ 

return(divide(total,oount,15)); /* Return quotient of average. */ 
end; /* average: proc */ 

end_avg: proc (avgLid) ; 

del avg_id ptr; 

dd 1 average_stream based (avg_id), 

2 count fixed bin (15), /* # of numbers. */ 
2 total fixed bin (31); /* Total value. */ 

free aver age_str earn; 
end; /* end_avg: proc */ 



As with the previous change, because the calling sequence of the 
subroutine has been changed, the method of calling the subroutine would 
have to be adjusted for all users of the subroutine, as indicated in 
the following example: 



do_average: proc; 

del current_avg fixed bin (15), 
next_junnber fixed bin (15), 
avg_id ptr; 

del tnou entry (char (80) , fixed bin(15)), 
tidee entry (fixed bin(15)), 
tovfd$ entry (fixed bin(15)), 
tnoua entry (char (80) , fixed bin(15)), 
init_avg entry returns (ptr), 
end_avg entry (ptr), 
average entry (ptr, fixed bin (15)) returns (fixed bin(15)); 

call tnouCEhter numbers. Type to stop, ',31); 
current_avg=0 ; 
next_number=-l ; 

avg_i*=init_avg() ; 

do while (next_jTumber''=0) ; 

call tnoua ('Enter next number; ',19); 

call tidee (next_number) ; 

if next_number''=0 then current_avg=average(avg_id,next_jiumber) ; 

end; 
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call en<i_avg (avg_id) ; 

call tnouaCihe average is '/IS); 
call tovfd${current_avg); 
call tnou(",0); 

end; 



This method has an advantage in that, in the future, the AVEIWGE module 
may add information to its AVEI?AGE_NUMBER based structure without 
affecting any callers of the module. As with the previous method, full 
reentrancy is realized even within a single program. To handle two or 
more simultaneous number streams, the main program needs only make 
multiple calls to INIT_J57ERflGE and END_JSLVERfiGE using different AVQ_n) 
pointers, and use the appropriate pointers in calls to IXLAVERAGE. 

Optimizing the General j^roach to Conversion ; Another example of the 
ability of Sii structure hinted at above is that if further 
optimization is needed when multiple number streams are used, the 
module can be changed to avoid frequent dynamic allocation of the 
AVEE?ft3^_£!TREAM structure. To reduce use of the manory allocation 
mechanism, a more efficient special-case mechanian can be constructed 
by reserving storage in the linkage area. This storage, called 
AVERAGE_£!TATIC, contains 50 potential copies of AVERAGEJSTtlEAM, v*iere 
50 is a number representing a typical figure for the maximum number of 
simultaneous number streams in use by a particular product. 

Of course, reestablishing the use of STATIC data causes the subroutine 
to beoOTie nonreaitrant once again. However, additional processing can 
be performed to manage the single linkage area that the subroutine uses 
as a process-class subroutine, so that separate program invocations use 
the same static AVERAGEJ5IREAM pool, without overwriting each other's 
data. Ihis produces a form of reoitrancy known as active reentrancy . 
Most FRIPDS system subroutines also practice active reentrancy, using 
methods similar to the one discussed here. 

Causing the AVERAGE module to employ active reentrancy can be done 
without changing the external calling sequence of the AVERflGE module as 
most recently shown above. However, major internal changes are needed. 

An important consideration is to code the AVERAGE module so that 
interruption of the module during the management of the STATIC data 
followed by invocation of another program that called INIT3VERAGE does 
not corrupt the linkage area. 
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When reooded according to these considerations, the AVERAGE module 
appears as follows: 



init_avg: proc returns (ptr); 

del 1 average_static(50) static ejcternal, 

2 inde^-St fixed bin{15) init((50)0), /* Index within the 

array. -1 means not in array, 
means not in use, >0 means in use 
and is index. */ 
2 count_intoj3ased fixed bin (15) init((50)0), 
2 total_intQj>ased fixed bin (31) init((50)0) ; 

dd 1 average_info static external, 

2 next_index fixed bin (15) init(l), 

2 have_ended_early_indexes bit (1) init ( ' ' b) ; 

del 1 average_stream based (avg_id), 

2 inde3t_into_static fixed bin(15) , /* Index within array. */ 
2 count fixed bin (15), /* # of numbers. */ 
2 total fixed bin (31); /* Total value. */ 

del i fixed bin (15), /* Temporary. */ 

avg_id ptr, /* Pointer to average data structure, */ 
cond_stQre_ok fixed bin (15) ; /* l=Conditional store worked. */ 

del concLstore entry (fixed bin (15), fixed bin(15) , fixed bin (15)) 
returns(fixed bin(15)); 

avg_id=null() ; 

do while (avQ_i6=null() ) ; 

i=next_index; /* See if we can get this element, */ 
if i<=hbound(average_static,l) 

then do; /* Some of array left. */ 

next_inde3F:i+l ; /* Either way, increment it. */ 
eond_stor^ok=oonl_st<a:e(indeK_st (i) ,i,0) ; 
if oond_stQre_ok=l 

then avg_i<J=addr(average_statie(i)) ; 
end; /* Or try again. */ 
else do; /* It isn't easy, consider searching lower. */ 
if have_ended_early_indexes /* Find free element? */ 
then do i=l to hbound(average_statie,l) ; 

eond_stQre_ok=cond_store(inde5L.st (i) ,i,0) ; 
if cond_stQre_ok=l 

then avg_i*=addr (average_static (i) ) ; 
end; /* Or try again. */ 
if avg_i*=null() /* If still not found, allocate. */ 
then do; 

allocate average_stresm set(avg_id); 
index_intQ_staticp=-l; /* Allocated. */ 
end; /* if avg_id=null() */ 
end; /* if i>hbound(average_statie,l) */ 
end; /* do while (avg_i*=null() ) */ 



First Edition 6-26 



LIBRARY EPFS 



count=0 ; 
total=0; 

return (avg_id) ? 

end; /* init_avg: proc */ 

average : proc (avg_id, number ) returns ( fixed bin (15 ) ) ; 

del avg_id ptr, /* Address of the average data structure. */ 
number fixed bin (15); /* The newest number. */ 

del 1 aver age_str earn based (avg_id) , 

2 indeK_into_static fibred bin (15), /* Index within arra^. */ 
2 count fixed bin (15) , /* # of numbers. */ 
2 total fixed bin (31) ; /* Total value. */ 

count=oount+l ; /* Another number. */ 
total=total+number; /* Total it up. */ 

return (divide (total, count, 15)); /* Return quotient of average. */ 
end; /* average: proc */ 

end_avg: proc (avg_id) ; 

del avg_id ptr; 

del 1 average_static(50) static external, 

2 indejt_st fixed bin (15) init((50)0), /* Index within the 

array. -1 means not in array, 
means not in use, >0 means in use 
and is index. */ 
2 oount_intQjDased fixed bin (15) init((50)0), 
2 tota]_into_based fixed bin (31) init((50)0); 

del 1 average_info static external, 

2 next_index fixed bin (15) init(l), 

2 have_ended_early_indexes bit(l) init('O'b); 

del 1 aver age_str earn based (avg_id), 

2 inde3^into_static fixed bin(15) , /* Index within array. */ 
2 count fixed bin (15), /* # of numbers. */ 
2 total fixed bin (31) ; /* Total value. */ 

del i fixed bin (15), /* Tanporary. */ 

oond_stor^ok fixed bin (15) ; /* l=oonditional store worked. */ 

del oond_store entry(fixed bin(15) , fixed bin(15) , fixed bin(15)) 
returns(fixed bin(15)); 

if inde3Linto_statie>0 

then do; /* Pointer to within array. */ 
i= inde3t_into_stati c ; 
indeJL_st(i)=0; /* Free again. */ 
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c!oncLstor^ok=coal_store(ne3ct_index, i, i+1) ; 
if ooni_store_ok=0 /* Wasn't most recent? */ 

then have_ended_early_indexes='l'b; 
end; /* if indeH_into_static>0 */ 
else if indeK_into_statio=-l then free average_strean; 
else step; /* This is an error. */ 
end; /* end_avg: proc */ 

To provide optinal performance, the INnLAVERftSE and END_J5lVERAGE 
procedures have undergone extensive changes. However, the AVERAGE 
procedure itself has remained unchanged, except for the new declaration 
of the average data structure. AVERAGE does not need to consider 
whether the pointer passed to it identifies storage within the linkage 
area or <^namically obtained storage. 

Instead, INIT_JSlVERAGE and WQjmSPGE together manage the external 
static (common) storage that is used for quick "allocation" of 
AVERflSELSIREAM structures. The AVERAGE_^ATIC array contains 50 copies 
of potential AVERAGE_SIREAM structures. NCw included in each structure 
is an INEEX that identifies whether the structure is available or not 
(within the array) , or separately allocated (not within the array) . 
Separate allocation occurs only when the arr^ of AVERAGE-STATIC is 
fully used, and hence represents a graceful degradation when more than 
50 number streams are in use at a time. 

An iirp)rtant subroutine used in the newest AVERAGE module is the 
OOND_STORE subroutine. This subroutine is a FMA module that takes a 
FIXED BIN (15) location in manory, a new value for that location, and an 
old value for that location. The GCNDJSTORE subroutine updates the 
FIXED BIN(15) location to the specified new value only if the old value 
is accurate. Otherwise, it leaves the location unchanged. It returns 
a 1 if it succeeds in updating the location; if it does not. 

Because it uses the SIPC machine instruction, the verification of the 
old value and update of the new value are guaranteed to occur in an 
atonic fashion, independent of any other processing on the system, 

A listing of GOND_STORE. PMA is found in Chapter 8, as it is a useful 
subroutine for updating information in shared memory. 

Methods such as those listed above may seen extensive, but they can 
result in better throughput for your product. In addition, when the 
target of such a procedure includes a number of separate subroutines 
that manage a single common area, folding them into one procedure with 
alternate entrypoints may improve the maintainability of that portion 
of your product. 
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Determining the Class Requirements of Your Library EPF 

Once you have determined the requiranents for all of the subroutines in 
the library EPF you wish to build, decide whether you will have one 
library EPF, either process-class or program-class, or two library 
EPFs, one ot each class. On a per-subroutine basis, the decisions are: 

• A subroutine that must be in one particular class must be placed 
in a library EPF of that particular class. 

• A subroutine that can operate in either class can be placed in 
either class, but will probably operate more efficiently when 
placed in a process-class library EPF. 

If you have subroutines in each class that require being in that 
particular class, then you must have two library EPFs, one of each 
class. 

If all your subroutines require being in the program class, or they all 
require being in the process class, then you must have one library EPF 
of the appropriate class. It is rare for a subroutine to require being 
in the process class, although dependencies on being in the program 
class are common. 

If none of your subroutines require being in the program class, then 
you need create only one process-class library EPF. Ihis is the most 
desirable situation, as it results in the best performance. 

Topically, however, you will have seme subroutines that require being 
in the program class, and others that can be in either class. In this 
case, you can create either one progr cm-class library EPF, or two 
library EPFs (one of each type) . 

"Hie tradeoff depends on the overhead of having PRIICS maintain 
information on a second library EPF, including a search list entry, 
certain internal resources on a per-library EPF basis, and two separate 
linkage initialization phases for using your library as a whole. 

If this overhead is less than the overhead of having PRIPDS reallocate 
and reinitialize linkage areas belonging to subroutines that do not 
require the program class, then having two library EPFs represents a 
reasonable performance tradeoff. 

Otherwise, the added overhead of a second library EPF for your library 
is not worth the savings of separating the linkage areas, so one 
program-class library EPF should be used. 



Note 

Because FRIMDS does not suH»rt d/namic linking to common 
areas, you must place all subroutines that reference a 
particular cciranon area in the same EPF as the common area 
itself. For example, if subroutines A and B wish to 
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(xmonnunicate via a common area named lOBUF, then both 
subroutines A and B and common area lOBUF must all be linked 
into one EPF. If instead you place subroutine A in a 
program-class library EPF and subroutine B in a process-class 
library EPF, for example, then they each get their own copies 
of lOBUF and therefore cannot communicate with each other 
through 3DBUF. 



HOW TO USE EBG ON A LIBRARY EPF 

Debugging a library EPF using EBG requires that the object (.BIN) files 
that comprise the library EPF be linked into a program EPF along with a 
subroutine that serves as as the main entrypoint for the program EPF. 
lypically, the main subroutine entrypoint is used only for detxigging 
and testing of the library EPF, and it does not necessarily require any 
code. It should, however, contain declarations for all subroutine 
entrypoints in the library EPF. 

You may find it useful to also declare storage in the main entrypoint 
of the program EPF, to be used during EBG CALL commands to subroutine 
entrypoints as storage for the input and output arguments. If you do 
this, you ^ould have the main entrypoint initialize all its variables 
so that an attempt by the user of EBG to examine some of the data (such 
as varying character strings) does not produce garbage output on the 
screen. 

The last statement executed by sudi a test bed is, in PLl/G: 
CALL SIGNL$('PAUSE$',NULL(),0,NULL(),0,'C000'b4)j 

In FTO or F77, use a PAUSE statanent. 

This signals a condition that is intercepted ty EBG, causing EBG to 
enter subcommand level without finishing execution of the progrem. 
(When the main progrem finishes, access to the variables declared 
within it are lost.) 

A sample main entrypoint subroutine mi^t be: 

test j3e(3_for_xy ^library: proc; 

/* Declare all the library entrypoints. */ 

del xyz_input_coQrdinates entry (fixed bin(15), fixed bin(15)), 
xyzL_plot entry (ptr, fixed bin(15) , fixed bin(15)), 
3cy2L.i?x3ate entry (ptr), 
3y2L_output_graph entry (ptr), 
xyzL_delete_user entry (char (32) var) ; 
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/* Declare storage used for library entrypoints. */ 

del X fixed bin(15), /* For XY2LINIUIL00ORDINATES. */ 
y fixed bin (15), 

grapJT_ptr ptr, /* For JQT^UHmTE and XiTZLOUTPOTLCSRAHI. */ 
user_jTame char (32) var; /* For xy^_J»LETEL.USER. */ 

/* Declare graph structure, */ 

del graj*i(24,80) char(l); 

/* Declare SIGNL$ subroutine. */ 

del signl$ entry (char (32) var,ptr, fixed bin (15 ),ptr, fixed bin(15), 
bit (16)); 

/* Initialize variables. */ 

x=0; 

y=0; 

graphj'tr=addr (graph) ; 

user_name=' '; 

graph=' '; 

/* Now pause, invoking LEG subcommand level. */ 

call signl$('EMJSE$',null(),0,null(),0,'C000'b4); 

/* If user continues, run the game. */ 

x=l; 

do while (x''=0) ; 

call 5y2Linput_coordinates(x,y) ; 

if x>=l & x<=80 & y>=l & y<=24 

then call X7?_plot(graFh.^r,x,y) ; 

end; /* do while (x^sO) */ 

call xy?_output_graph(graph_ptr) ; 
do while Cl'b) ; 

call signl$('PAUSE$',null(),0,null(),0,'C000'b4); 

call }^?_i;pdate(graph_Ftr) ; 

call x72L.output_graph(graphjitr) ; 

end; 

/* End of test bed. */ 
end; 
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Build the test bed program EPF by linking the main test bed subroutine 
with the object files used that comprise the library EPF. Tlien, type: 



DBG test-bed-progran 
RESTART 



Bie FESTMIT command causes the work area variables to be initialized. 
The main program is then suspended, returning you to EBG mode. At this 
point, you can either CONTINUE the main program to perform typical 
system or unit tests, or use the CMi subcommand to test the behavior 
of specific subroutines in your library. 



EMTRYIOINT SEARCH LISTS 

PRIMDS makes the connection between a library EPF and a program that 
wishes to use the library EPF when the program attempts to call a 
subroutine in that library EPF. "Hiis causes the ^namic linking 
mechanism to be invoked. "Hie dynamic linking mechanism is described in 
Chapter 2. 

When the dynamic linking mechanism is invoked, it first searches the 
list of internal ERIM3S entrypoints. If the desired subroutine is not 
found there, the ^namic linking mechanism uses an entrypoint search 
list to direct it to library EPFs that are to be searched for the 
"aisired subroutine. In addition, the search list specifies at what 
point the static-mode libraries are to be searched, if they are to be 
searched. 

Each user has an in-manory copy of an entrypoint search list. Tliis 
in-memory copy is loaded frcm a file on disk with the name EtnRY$.SR or 
with a name ending in .EinRY$.SR. The file is loaded into memory 
either : 

• When the first dynamic link for a user is encountered 

• When a user issues the SETLSEAROODLES command (abbreviated 
SSR) 

If the first dynamic link is encountered before a user issues the 
SET_SEARCHLJ'ULES command after logging in, ERIIOS loads the default 
entrypoint search list , which has the patimame sySTEM>ENTRY$.SR. 

A user may use the SETJSEARCRJRDLES command to switcdi to a new 
entrypoint search list or to return to the default entrypoint search 
list. 

Typically, the default entrypoint search list indicates that 
system-wide library EPFs (in the LIBRARIES* UFD) are to be searched 
first (after internal ERINDS entrypoints, which are always searched 
before any libraries listed in the entrypoint search list) . These 
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libraries include the system library (SYSTEMJilBRARY) , the FORTRAN I/O 
library (PORTRAIsLKlJLIBRARY) , the application library 

(APHalCATlDNJilBRARy) , and so on. 

At some point, the default search list usually directs that the 
static-mode libraries are to be searched. Although Prime supplies 
several individual static-mode libraries, these libraries are treated 
by the seardi list mechanism as one library. If the desired subroutine 
is still not found, the default search list may specify further library 
EPFs that are to be searched. If the end of the search list is reached 
and the target subroutine has still not been found, the dynamic linking 
mechanism signals the condition LINKAGE_FAULT$, which typically 
produces an error message such as: 



Error: condition "LINKAGELFAULT$" raised at 4243(3)/1031. 
Entry name "INnLJiINE" not found while attempting to resolve 
dynamic link from procedure "TRYJ^YNC" . 
ER! 



An entrypoint search list consists of one or more search rules . A 
particular line within a search list is referred to as a search rule 
(singular) . 

To display your current search list, use the LIST_SEARaLJPDIiES command 
(afctoreviated LSR) . For example: 



OK, LISTJ5EARCEUULES 

E^thname of template: <SYSDSK>SYSTM>ENTRY$.SR 

LIBRARIES*>SYSTEIU:iIBRARY. HJN 
LIBRARIES*>APHjICAT3DNJiIBRARY.FUN 
-STATIQJDDEJilBRARIES 
LIBRARIES *>PLiq_LIBRARY. BUN 
LIBRARIES *>PORTRAN_ID_JiIBRARY. HJN 
LIBRARIES *X]OMMDNJNVELOEE . HJN 
LIBRARIES*X)PPIMIZER. HJN 
LIBRARIES*XX)DBGEH_CDiyMDN.HJN 
LIBRARIES *XX)r»GENV. HJN 
L]BRARIES*X]ODBGENI. HJN 
LIBRARIES*XBItJiIBRARY. HJN 
LIBRARIES*X:QJiIBRARY. HJN 
LIBRARIES*>PASCM,JjIBRARY. HJN 
LIBRARIES*>VRKLJiIBRARY. HJN 
OK, 



As shown in the above sample, the default system search list comes from 
the file SYSTEM>ENTO.Y$.SR. All entrypoint search rule files must be 
named ENTRY$.SR, or eid in .EJJTRY$.SR, to identify them as library 
entrypoint seardi rule files. 



6-33 First Edition 



PJJjmCED IROGRAMNER'S GOTIE, VCLUWE I: BIND AND EPFS 



Notice that the static-mode libraries are identified using the 
-STATICJDDELJilBRARIES option. 

Hie file containing the search rules, S^STEM>EOTRY$.SR, is a text file 
that contains the lines shown in the above sample. As with other text 
files, the file can be modified by using text editors such as ED or 
EMACS. The file corresponding to the above sample search list is shown 
below: 



LIBRARIES *>SYSTEMJLIBRRRY. FDN 
LIBRARIES*>APPLICATIDllJiIBRARY. HJN 
-OTATIQJCDELJjIBRARIES 
LIBRARIES*>ELlQJiIBRARy. HJN 
LIBRARIES*>P0RIRAN_D_JLIBRARY. HJN 
LIBRARIES *X»MMDN_ENVELOFE . HJN 
LIBRARIES*X)EriMIZER. HJN 
LIBRARIES *XX)DE)GEN_a)Ml>CN.HJN 
LIBRARIES*X]ODBGENV. HJN 
LIBRARIES*>a)DBGENI. HJN 
LIBRARIES*>CBItJiIBRARY. HJN 
LIBRARIES *XXLJ:.IBRARY. HJN 
LIBRARIES*>PASCALJjIBRARY. HJN 
LIBRARIES*>VRPG_LIBRARY. HJN 

The ordering of individual rules is important, as it reflects the order 
in which liie libraries are searched. The search order is iirportant for 
performance reasons, as frequently-called subroutines (such as the 
st±)routines in SYSTEMJLIBRARy) should require the shortest search time 
possible. In addition, the search order is iirportant when naming 
conflicts occur between libraries — the order in which the conflicting 
libraries appear decides which copy of a subroutine is actually 
invoked. 



Setting Your Own Search Rules 

Setting your own private search rules is iirportant vAien you are 
developing a library EPF. Only ty updating your search rules do you 
enable programs that you run to be able to call, or link to, 
subroutines in your library EEF. This section discusses how to set 
your own search rules. 

First, you create your own search rule file. It must be named 
ENTRY$.SR, or Old in .ENTIIY$.SR, to be considered a valid entrypoint 
search rules file. 
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The simplest form of this file is: 



-SYSTEM 
MYUFD>iyKLIBRfiRY. HJN 



"Hie -SYSTEM rule specifies that the standard system search rules, found 
in SYSTEM>ENIRY$.SR, are to be seardied, and then the library EPF 
specified is to be searched. The contents of SYSTEM>EMRY$.SR replace 
the -SYSTEM rule in memory at the time you issue tJie SET_SEi5lCILPDIiES 
command, not later when dynamic linking takes place. 

Keep in mind that these lists are. searched only vrtien the dynamic 
linking mechanian is actually invoked. Until a subroutine in your 
library EPF is called, it may not necessarily be mapped into memory. 



Note 

The -SYSTEM rule affects the ordering of the search only if the 
-NDlSYSTEM option is specified on the SET_J5EARCELJ5ULES command 
line, as described below. Otherwise, -SYSTEM is ignored, and 
the search rules in the default entrypoint search list are used 
before the search rules in the personal entrypoint search list. 

Although -SYSTEM is ignored, you should place it in the file as 
shown, just in case somebody accidentally specifies the 
-NQJSYSTEM option on the SET_SEMICELJDLES command line. The 
side effects of having only one search rule in an entrypoint 
search list are very strange and difficult to identify. 



A more complex method of creating your search rules file is to actually 
list all of the libraries to be seardied, in the order you desire. For 
example: 



MYUFD>MXLIBRARY. HJN 
LIBRARIES*>SYSTEM_I.IBRfiRY. HJN 
LIBRARIES*>PORTt?AMJiIBRARY. HJN 
LIBRARIES*>PORI!RAN_lD_JiIBRARY. HJN 
LIBRfiRIES*>APH:iICAT]DN_LIBRflRY, HJN 
-STATICJDDELLIBRARIES 



This has an effect similar to the previous search rules file, except 
that the library EPF MYUFD>MXLIBRARY.HJN is searched before any other 
library is searched, with tiie exception of internal IRIMDS entrypoints. 

Once the search rules file is created, you establish it for the 
duration of your login session using the SET_SEMlCILJ'UIiES command. 
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Tlie format of tiiis ooiratand is: 



SETLSEARCJUPLFIiES | search-rules-file.EOTRY$ [-N3_SYSTEM] 
SSR 



Ihis changes your current search list to the search rules specified in 
search-rules-file . EMRY$.SR. You will revert to the standard system 
search rules (in SYSTEM>ENIRY$.SR) only vAien you log in again, when 
your oomnand envirorment is reinitialized, or when you issue the 
oomnand: 



SETLSEARCaj'ULES -DEFAULT ENTRY$ 



To make changes to your search list permanent, update your LCGIN.CPL or 
LOGIN. CDMI file to include the appropriate SET_jSEARaoDLES command. 

The -^D_JSYSTH1 option, when present, indicates that the default syston 
search list, SYSTEM>ElsnRY$,SR, is not to be automatically inserted in 
front of your search rule when you issue the SETjSEMiaouiiES command. 
You should use this option only if you have used a copy of the default 
syston search list to build your own search rule. Careless use of the 
-ND_J5YSTEM option may cause erratic bd:iavior in Prime-suppLied 
programs. 



Caution 

Do not use the SET_5EARCEOULES command while there are active 
program or library EPFs in your command environment, except to 
add new library EPFs that you are developing to the end of the 
list (after the -SYSTEM rule) . It is recommended that you use 
the INITIALIZELGONIMftND_ENVlRCrMENT command before each use of 
SET_SEARaoULES. It is not intended for the active search 
list of a user to be frequently changed. Deleting or modifying 
particular rules in the search list while active EPFs abound is 
likely to cause inconsistent program behavior. 



If your login program (LOGIN.CEL, LOGIN.aOMI, LOGIN.HJN, or LOGIN.SAVE) 
sets up your search rules, then use of the 

INITIAL IZE_CDMMftND_JNVIRCNMENT command, which invokes your login 
program, also causes your search rules to be set up. 

In this case, either modify your personal copy of the search rules so 
that your login program uses the correct copy, or modify your login 
program to use the new copy that you have constructed. 
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Advanced Use of Entrypoint Search Lists 

In some cases, there may be three levels of entrypoint search list 
activity: 

• The system-wide search list, maintained ty the System 
Adninistrator 

• The search list for a particular application or project, v^ich 
changes relatively frequently 

• A user who has his or her own library EPFs and who therefore has 
a personal search list, yet needs to also utilize the other two 
search lists 

In this case, the user mi^t have difficulty maintaining his or her 
personal search list so that it reflected the latest changes for the 
application or project he or she is associated with. 

A solution to the problem is to place search rules specific to the 
application or project in a central entrypoint search list file. Then, 
personal search lists can use the special rule -USE to refer to the 
project list. 

For example, a project-wide entrypoint search list file named 
ERCaBCr_A>ENTRY$.SR mi^t read: 



PRaJBCr_J^ASYNCLJiINE . HJN 

ERcaBcr.j^x. 25_aoMiyB . hjn 

HlCaBCT_J^SCREQq_PORMS . HJN 



A personal entrypoint search list file might then read: 



-SYSTEM 

-USE HiajEcr_j\>EiraRY$ 

MyDIR>MXLmRARY. HJN 

Anytime the SET-SEARCELHJLES command is issued for the personal 
entrypoint search list file, the project-wide entrypoint search list 
file is autcmatically included. 

This allows the project leader of IRCJBCnLA to change the project-wide 
search list file without having to ask users on the system who have 
their own personal entrypoint search list files to update their files. 
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EXAMINING EMRYIOINT LISTS 

You can examine the list of entrypoints for either a library EPF or a 
particular library (.BIN) file. 



Examining Entrypoints in a Library EPF 

You may examine the list of entrypoints for a library EPF by using the 
LIST_JiIBRARY_EJsnRIES command (abbreviated LLHSIT) . Tliis is useful when: 

• You want to check other library EPFs use at your installation 
for possible conflicts with names you intend to use as 
entrypoint names 

• You want to check that you have declared all entrypoints in your 
own library EPF correctly 

• You want to determine in which library EPF a particular 
entrypoint exists 



Checking a Particular Library EPF 

To check a particular library EPF for whether it declares a particular 
name as an entrypoint, or to list all of its entrypoints, use the 
ocmmand: 



LIST_J.IBRARY_JNTRIES epf-filename [-ENIRYNA^E name ...] 

It does not matter whether the library EPF you are checking is yours or 
not. 

The library EPF is epf-filename . You may specify as many as ei^t 
entrypoint names ( name ) to search for, or you may leave off the 
-E^P^lYNA^E specification to display all of tiie entrypoints for the 
library. 



Locating a Particular Entrypoint 

To determine in which library EPF a particular entrypoint exists, use 
the following form of the LISTJLIBRfiRY_JNTRIES command: 



LIST_LIBRARY_ENIIIIES -ENTRYNATE name ... 
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All library EPFs specified in your entrypoint search list are checked 
for the existence of the entrypoint named name . (You may specify as 
many as ei^t entrypoint names.) 

If any library EPFs specified in your oitrypoint search list are 
inaccessible for seme reason, such as when a library EPF does not not 
exist in the specified directory, LIST_JiIBRARY_JNTRIES displays an 
error message. Therefore, LISTJLIBKfiRYJNIRIES may be used to verify 
the correctness of an entrypoint search list. 



THE LIBRARY EPF MECHANISM 

•fliis section describes specific aspects of the EPF mechanism that apply 
only to library EPFs. Thorough familiarity with the description of the 
EPF mechanism found in Chapter 3 is a prerequisite for understanding 
this section. 

Specifically, this section describes: 

• The autonatic mapping of library EPFs during dynamic linking 

• How ERIMDS decides whether to skip Hiases 5 and 6 of the EPF 
mechanism for a library EPF 

• Storage allocation issues relating to library EPFs 



The Autonatic Mapping of Library EPFs 

The only way a library EPF is accessed by another program is by 
encountering a dynamic link (via a faulted IP) that identifies, as its 
target, an entrypoint in the library EPF. 

The dynamic linking mechanism, described in Chapter 2, detects the 
faulted IP. After it has searched the internal HIIMDS entrypoints for 
the desired subroutine, it uses the user's entrypoint search list to 
determine where to look for the desired subroutine next. 

Each rule in the entrypoint search list is either: 

• The pathname of a library EPF 

• The rule -aPATIC_fDDE_j:jIBRARIES which indicates that the 
static-mode libraries are to be searched 

• The rule -SYSTEM which indicates that the default entrypoint 
search list, SYSTEM>ENTRY$.SR is to be searched; this list has 
in it only rules of the first two types listed above 
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When the dynamic linking mechanism encounters a pathname rule, it 
checks to see v^ether the library EPF identified by the pathname is 
alrea(%7 mapped in. If it is not, the dynamic linking mechanism most 
map the library EPF into manory (Phase 4 of the life of an EPF, as 
presented in Chapter 3) before it can searcJi its list of entrypoints. 

Once the library EPF is mapped in, the (%mamic linking mechanism 
searches its list of entrypoint names to see if it contains the desired 
subroutine. If not, the library EPF remains mapped-in but inactive. A 
library EPF is removed only by a user command (such as RENDVELEPF) or a 
call to the EPF$DEL subroutine. 

If the library EPF does contain the desired subroutine, the dynamic 
linking mechanism does not need to map it in because it has already 
been mapped in. Instead, the dynamic linking mechanism checks to see 
if it needs to allocate and initialize linkage for the EPF, as 
described next. 



Phases 5 and 6 of the EPF Mechanism 

In the life of an EPF, presented in Chapter 3, Hiases 5 and 6 are: 

5. Ihe linkage (impure) portion of the EPF is allocated 
(EPF$ALLC) . 

6. The linkage (impure) portion of the EPF is initialized 
(EPF$INIT) . 

Each time the dynamic linking mechanism processes a dynamic link to a 
library EPF, it must determine whether it needs to allocate and 
initialize the linkage (impure) portions of that EPF. This decision is 
primarily based upon whether the library EPF is program-class or 
process-class, and whether it is already in use (by the program or hy 
the process) . 

Program-Class Library EPF ; For a program-class library EPF, the 
dynamic linking mechanism checks to see whether the program invoking 
the library EPF has alrea<%r linked to the same EPF. If it has, then 
the injure portions of the library EPF that correspond to the program 
have already been allocated and initialized, and Phases 5 and 6 are 
skipped. 

■Hie iirpure portions of a process-class library EPF are deallocated 
whenever the user changes command levels, unless the library EPF is in 
use by a suspended program, (This behaviour may change at future 
Revisions of IRIMDS.) 



First Edition 6-40 



LIBRRRY EPFS 



Process-Class Library EPF ; For a process-class library EPF, the 
d/namic linking mechanisn checks to see whether the EPF has already had 
its inrpure portions allocated and initialized. If it has, then Phases 
5 and 6 are skipped. Even if a different program caused the allocation 
and initialization of the EPF, Ehases 5 and 6 are skij^d, because only 
one copy of the iirpare portions of a process-class library EPF are kept 
for a user, and they are not reinitialized when a new program starts 
using the EPF. 

Impure portions of a process-class library EPF are deallocated when: 

• The user logs out. 

• The user ej^licitly removes the process-class library EE^ by 
using the REM3VE_EPF command. 

• The user's oomrrand environment is reinitialized, either 
explicitly (via the INITIALIZE_CDMMRND_JNVIRCNMENT command) or 
implicitly (as a result of an error condition detected by the 
command envirorment and identified as being unresolvable) . 

However, a process-class library EPF that is still in use by a 
suspended or running program cannot have its impure portions 
deallocated. 



Storage Allocation Issues 

The Prime 50-Series architecture allows the dynamic allocation of stack 
space during procedure call. In addition, HRINDS allows the dynamic 
allocation and deallocation of memory via explicit requests by a 
running program. 

Eynamic manory is allocated during program runtime as a result of 
either : 

• Compiler-generated requests for tonporary storage, sudi as for 
the storing of a tonporary character string during the execution 
of a string concatenation operation 

• Program-directed requests for memory, such as via the ALLOCATE 
statanent in PLl Subset G 

Kkjrmally, manory dynamically allocated by a program is autcmatically 
deallocated (freed) by PRI^DS when the program terminates. In 
addition, an/ manory dynamically allocated by program-class library 
EPFs invoked by that program is also deallocated. 

However, manory ^namically allocated by a process-class library EPF 
must not be deallocated by ERIMDS when a farogram terminates. This is 
because the linkage portion of that EPF, whidi may contain pointers to 
the dynamically allocated manory, is not deallocated; it is instead 
reused. 
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Therefore, IRIM3S must distinguish between a program-class library EPF 
and a process-class library EPF when allocating memory to ensure that 
it does not, later, autcmatically deallocate memory acquired by a 
process-class library EPF, 

This distinction is made during the linking of the library EPF. For a 
process-class library EPF, using the LIBRARY PROCESS_CLASS subcommand 
specifies that dynamically allocated memory is to be acquired from a 
special memory pool, called process-class stcarage . No memory from this 
pool is ever explicitly deallocated ty HRIWDS except during logout and 
command environmait initialization. 

If the LIBRARY PROCESS-CLASS subcommand is not used, as for a 
program-class library EPF, dynamically allocated memory is acquired 
frcm the program-class storage pool used by program EPPs. Memory 
allocated from this pool Ey a particular progran is autcmatically 
deallocated by HRIMDS when the progran terminates. 

If a process-class library EPF is built without the LIBRARY 
PROCESS_CLASS subcommand, then any language-driven allocation, either 
explicitly via statonents such as ALLOCATE in PLl/G, or implicitly via 
ccanpiler-generated allocation for temporary storage, will fail when the 
library EPF executes. The failure will be in the form of a 
LINKAGEJKRDR$ condition raised. Ihe condition is raised because the 
process-class library EPF attanpted to link to a program-class library 
EPF in which the program-class allocator resides. 



Caution 

A pointer to storage that has he&n dynamically allocated as 
program-based storage should not be passed to a process-class 
subroutine if that subroutine stores the pointer in linkage 
area or in dynamically allocated manory. Similarly, the 
address of a program-class entrypoint should not be passed to a 
process-class subroutine unless the subroutine stops using the 
address when it returns to its caller. 

In general, a pointer to object A should never be passed to 
subroutine B if the life-span of the storage used by subroutine 
B to hold the pointer to object A may exceed the life-span of 
object A itself. Otherwise, the termination of object A 
followed by the continued execution of subroutine B may result 
in the reference by B to the (nonexistant) object A, producing 
unpredictable (and invariably incorrect) results. 

While this is a general principle of programming methodologies, 
it applies specifically to the interactions betweai 

program-class subroutines and process-class subroutines. 
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Coding Guidelines 
for EPFs 



This chapter describes the ooding guidelines that you should f ollcw 
when writing subroutines or main programs that are going to be built as 
EPFs, None of these guidelines preclude the use of these subroutines 
and main programs in static-mode applications built with SEG e»:ept as 
otherwise noted. 

Specifically, this chapter describes: 

• How to write modules in Prime-suppLied hic^-level languages for 
EPFs 

• How to write modules in JMA (Prime Macro Assembler) for EPFs 



WRITIN3 M3DULES IN HIGH-LEVEL LfiNGUASES FOR EPFS 

Most Prime-supplied language compilers produce EPF-oompatihle object 
(.BIN) files. These languages include: 

• F77 

• Pnsi (vhen using the -64V or -DYNM options) 

• Pascal 

• PLl/G 

• VRPG 
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• CBL 

• C 

Using these compilers always produces EPF-compatible object files. An 
exception is the FTO compiler when the -IBBCB option is specified. If 
-IBECB is specified on the FIN command line, BIND produces a warning 
message when the generated object file is linked: 

Warning: ECB mPRCG loaded into PROC segment . 



If this warning message appears, it indicates that the EPF is not 
likely to successfully execute when invoked. 

When the -EBBCB option is used with compilers other tiian FTN (for those 
compilers that support the option) , the compilers mark the compiled 
modules as inpure. BIND places procedure text for impure modules in 
the linkage area in specially marked segnents called IMHJRE segreients. 
Ihis allows FRIMDS to modify the ECBs when the program is executed, 
while preventing the procedure text for such modules from being shared 
between users and from being mapped directly from tihe file system disk. 
Iherefore, while -IBBCB may enhance the performance of a shared 
static-mode application, it typically reduces the performance of an 
EPF. 



Writing the Main Entrypoint of a Program EPF 

You write the main entrypoint of a program EPF exactly as you would 
write a subroutine. You may use the ERCGRAM statement (instead of the 
SUBROUTINE statement) in F77 or the OPT nONS (MAIN) keyword (on the 
PROCEDURE statement) in PLl/G if you desire. However, neither of these 
conventions is required for a main entrypoint. Requirements for the 
calling sequence of main entrypoints are described in the Programmer's 
Guide to BIND and EPFs and in Volume III of this series. 

Note that a program built via SEG in a fashion that produces a 
RESUMEable static-mode runf ile typically requires the main entrypoint 
to be named MAIN. No such requiranent exists for BIND and EPFs; 
however, you may wish to keep the SEG requirement in mind if you intend 
to use a main entrypoint in both the EPF and static-mode environnents. 



WRITING M3DULES IN PMA FOR EPFS 

This section summarizes basic concepts of FMA (Prime Macro Assembler) 
programming, and then discusses specific requironents for writing PMA 
subroutines that are to execute as EPFs. 
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Basic Concepts of IMA Programming 

A PMA source file is referred to as a module . It may contain one or 
inore subroutines . When a module is assanbled (using IMA), an object 
file is generated, usually with the .BIN suffix on its file name. Tliis 
object tejct consists of: 

• Module description information 

• Procedure text for each subroutine 

• Linkage text for each subroutine 

• Stack and parameter allocation information for each subroutine 
entrypoint 

• Linkage information for each subroutine entrypoint 

• External linkage information, including references to common 
areas and other subroutines 

You tell PMA which part of the module you are building by including 
special pseudo instructions in the PMA source code. Pseudo 
instructions are directives to the assembler; usually, they change the 
w^ in which subsequent lines in the source file are interpreted. 
Pseudo instructions themselves may or may not cause specific data (such 
as instructions or storage allocation information) to be generated in 
the object text. 

All IMA modules must have the END pseudo instruction as the last line 
in the file. PMA modules that serve as main entrypoints for a program 
(whether an EPF or a static-mode program) must name the main 
entrypoint 's ECB in the operand field of the END pseudo instruction. 
No comment lines or blank lines may follow the EM) pseudo instruction. 
Other important pseudo instructions are described belcw. 

PMA subroutines that are to be linked into EPFs are usually constructed 
according to the following tanpiate: 

Source Text Meaning 

• Ccmment lines describing the subroutine 

SBG or SBGR Pseudo instruction to specify a V-mode or 
I-mode module 

SYML Optional pseudo instruction to turn on long (as 
many as 32 character) symbol names 

RLIT Optional pseudo instruction to cause placement 
of literals in procedure text 
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LINK 
ECB 

DYNM 

EXT 

EROC 

instructions 
LINK 

data 



END 



Optional pseudo instructions to ejqwrt names 
for reference ty external modules 

Pseudo instruction to switch to linkage text 
generation for placement of the ECB 

Pseudo instruction to generate the ECB itself, 
and, optionally, additional ECBs for alternate 
entrypoints or internal subroutines 

Pseudo instructions to specify stack frcme 
allocation 

Optional pseudo . instructions to specify 
external symbols 

Pseudo instruction to switch back to generating 
procedure text 

The procedure code of the module 

Optional pseudo instruction for switching to 
linkage text generation 

Various address definition, data definition, 
and storage allocation pseudo instructions 
(optional) , to describe the format and data for 
the link frame 

Pseudo instruction to delimit the end of tiie 
module and optionally designate tiie main 
entrypoint of the module 



The remainder of this section describes portions of the object text and 
of the above template that are specifically related to coding a FHA 
module for execution within an EHE". See the Assembly Language 
Programmer's Guide for further information on FMA, For information on 
the instruction sets and architecture of the Prime 50 Series machines, 
see the System Architecture Reference Guide . 



Use of SBG or SBGR: 



The first 
either the 



non-comment line of a proper IMA 

subroutine must be either the SEG pseudo instruction (for a V-mode 
subroutine) or the SBGR pseudo instruction (for an I-mode subroutine) . 
If this is not the case, BIND refuses to link the object text (.BIN 
file) generated by asssonbling the subroutine via FMA. Additionally, 
the keyword HJRE or IMTORE should follow the SEG or SBGR keyword on the 
same line, as described below in the sections on Impure PMA Module 
Restrictions and Pure IMA Modules . If neither R3RE nor IMRJRE is 
specified, the default is PURE. 
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Procedure Text ; The procedure text for a subroutine consists of the 
instructions that make up the body of the subroutine. In a FMA 
subroutine, procedure text generation is specified via the pseudo 
instruction: 



EROC 

Linkage Text ; The linkage text for a subroutine consists of static 
data used and modified ty the subroutine. Only one copy of linkage 
text exists for a subroutine within a program or library, even if the 
subroutine invokes itself recursively. Linkage text generation is 
specified via the pseudo instruction; . 



LINK 

Stack and Paraneter Allocation information ; The D5fNM pseudo 
instruction is used to specify the allocation of the stack frame for 
the module. The stack frame is also used to hold the argument list 
pointers for the subroutine invocation. Eadi subroutine invocation 
causes the dynamic allocation of its stack frame. Initially, a stack 
frame contains undefined values except for the stack frame header and 
the argument pointers (if any) . 

Typically, the mm. pseudo instruction is used in the following manner; 

DYNM temporary-l(size-l) ,temporary-2(size-2) 

DYNM argument-1 (3) ,argument-2 (3) ,arguroent-3 (3) ,argument-4 (3) 

DYNM temporary-3(size-3) ,temporary-4(size-4) 

The argument list pointers must be allocated 3 hal&zords each, and must 
be contiguous in the stack freroe as indicated. Other temporaries can 
precede or follow the argument list template in the stack frame. The 
start ot the argument list template in this case is arqument-1 , and the 
number of arguments is 4. 

The imM pseudo instruction provides the only way of allocating stack 
frane storage in FMA. Using an BQU pseudo instruction to set a symbol 
equivalent to, say, SB%+102 does not affect allocation of the stack 
frane in any way. 

Use of D^NM changes allocation of storage to the stack frame only 
temporarily. The current assembly pointer is still either in procedure 
or linkage text, so machine instructions and data generation directives 
following DYNM are placed in either the procedure or the linkage area 
rather than the stack frame. (You cannot specify initial values for 
storage in the stack frame except by including prologie code in your 
subroutine to perform the initialization at runtime.) 
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Linkage Infoinnation ; Information for each subroutine entrypoint that 
describes the entrypoint to BIND is called linkage information . Its 
purpose is to tie together the procedure text, linkage text, and stack 
and parameter allocation information for the entrypoint. 

This information is turned into an EXB (Entry Control Block) for tiie 
entrypoint by BIND. When the EPF is invoked, IRIMDS modifies the ECB 
for each subroutine in the EPF so that the pointer to the linkage text 
in each ECB identifies the actual location of the linkage text. For 
this reason, a JMA subroutine that has its ECB in the procedure text 
bd:iaves as an iirpure subroutine if it is linked into an EPF via BIND. 

Linkage information is declared via the ECB pseudo instruction. Here 
is a sample use of the ECB pseudo instruction: 



LINK 
ecb_label ECB first_instructionJLabel,,first_arg,n_args 



This ECB is placed in the linkage text for the module. "Hie label for 
it is ectLjLabel and identifies the actual target of procedure call 
(PCL) instructions to the entrypoint. The ENT pseudo instruction is 
used to associate the es^rted (externally available) syntol name with 
edD_label : 



ENT external_name, ecb_label 



If external_name and e<±>_label are the same name, then only ENT 
ecb_label need be specified. 

The label of the first instruction to be executed (an ARGT instruction 
when the procedure has one or more arguments) is identified via 
first_instruction-J.abel . The label of the start of the argument list 
template is first_arg and must refer to a stack-relative label 
(declared via the D5fNM pseudo instruction) . The number of arguments is 
specified as n-args . 

■flie ECB pseudo instruction can be used to specif other information not 
described above. For example, between the two commas in the form 
above, you could define the start of linkage text for the entrypoint. 
It defaults to the start of linkage text for the module, as indicated 
via the LINK pseudo instruction. Another optional field, the stack 
size, defaults to the amount of stack space explicitly reserved via the 
D5fNM pseudo instruction. You can also specify the initial value of the 
keys register via ECB, although it defaults (appropriately) to the 
addressing mode of the module (V-mode or I-mode) . 



External Linkage Information ; A Ffih module must often refer to sytrtools 
.tiiat are not defined within the scope of the module itself. These are 
called external references. 
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A reference to a st±>routine that is defined externally is a reference 
to an external subroutine . For the most part, references to external 
subroutines are handled autcmatically by IMA via the CALL pseudo 
instruction: 



CALL subroutine 

When PMA detects a CALL pseudo operation while assanbling V-mode or 
I-inode code, it: 

• Identifies subroutine as an external reference, as if the pseudo 
instruction EXT subroutine had been issued 

• Places one IP (Indirect Pointer) in the linkage text that points 
to the external subroutine at runtime, for use fcy all CALLs to 
that subroutine in the current module, as if the following 
instruction sequence had been present: 

LINK (Switdies to generating linkage text) 
subroutine_ip IP subroutine 

IROC (Only if originally in procedure text) 



• Generates a procedure call instruction to invoke the subroutine, 
identifying indirection through the IP it generated as the 
target of tiie instruction: 

PCL subroutine_ip, * 

All of the above can be explicitly specified fcy the FMA programmer, but 
use of the CALL pseudo instruction is recommended when calling external 
subroutines. (To call a subroutine within the current module, use a 
PCL to its ECB without specifying indirection.) 

Another form of external reference includes references to program 
caranon areas and other syirtols. Here, mk also autanatically generates 
IPs and inplicitly forms indirect instructions that refer to the 
external symbols. However, the symbols must be explicitly declared as 
external as follows; 



EXT symbol 
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Caution 

Do not use the XAC pseudo instruction or its equivalent EXT/DAC 
pair in V-raode or I-mode EMA modules. EMA does not treat this 
usage as an error; however, neither BIND nor SEG support that 
form of external link (DAC and XAC generate only a 16 -bit 
halfword link) , and PRIMDS does not suj^rt the conversion of 
an imaginary 16HDit address to an actual 16-bit address. 



The OOMM pseudo instruction is particularly useful for building 
representations of common areas. PMA autonatically generates IPs for 
references into common areas, including references into the midst of 
common areas. In other words, PMA does not generate a single IP to the 
beginning of a common area and then use offset addressing (via the XB 
or X registers) to access items within the common area. Instead, PMA 
generates one IP for each reference into a common area at a different 
offset. This method produces more efficient code in terms of execution 
time at the es^jense of the size of linkage text (as more than one IP 
may be needed to access each common area) . It also allows IMA to avoid 
making de facto use of the XB or X register, either or both of which 
may be used by the programmer in nei^boring instructions. However, 
because EMA must convert instructions referencing common areas so that 
they go indirect through IPs, the instructions in the source program 
cannot specify indirection. 

If you want to refer to items within a common area using offset 
addressing rather than directly through an IP, you must use either the 
XB or X register. To use the XB register, code the instruction: 



EAXB caonmon_area (Becomes common_area_ip, *) 

Then, your program performs subsequent r^erences to items within the 
common area fcy referencing XB% +offset , where offset is the offset of 
the item, in halfwords, from the beginning of common_area . 

To use the X register, code the instruction: 
LDX =of fset 



Subsequent references to the iton that is offset hal&(?ords from the 
beginning of commori_area are performed by referencing commoii_area ,X. 
For example: 



LDA ccMnmorL.area,X 
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Because ooinmoi\_area is an external, PMA autcmatically translates this 
into: 



LEA cx3rnnHDn_area_iPf *X 

Therefore, you cannot perform indirection through a pointer in a ooinmon 
area without using effective address calculation and the XB register. 



Note 

When using the XB or X register, remember that, as with all 
other general-purpose registers, the POL (also CALL) 
instruction may destroy the register contents. 

Designating the Main Entrypoint ; If you are writing a PMA module that 
is to contain the main entrypoint for a program EPF, you must designate 
the main entrypoint of the module by specifying the symbol name for the 
BCB in the operand field of the END pseudo instruction at the end of 
the module. For example: 



SEG 

ELIT 

SYML 
* 

SIBR aOONr,CXXJNr_BCB 
* 

LINK 
CXXJNUJBCB BCB OOUNr_jSTi«T, , OOMMRND_JiINE, 2 
* 

D^M OOMMAND_JiINE (3) , SEVERITY_CDIX; (3) 
* 

PROC 
* 

coamL^mT bqu * 

ARGT 



END OOUNTBCB 



As this example illustrates, you must specify the label that tags the 
ECB for the nain entrypoint (COUMLBCB) , not the external name of the 
subroutine (CXXJNT) or tiie starting address of the procedure code 
(CXXJMPJSTART) . 
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If you specify the main entrypoint in this fashion, you nvay still use 
the module as a subroutine rather than a main pcogrem; in this case, 
your specification of the main entrypoint is ignored. 

If you fail to specify the main entrypoint as shown, linking the 
assembled module as the first module in a program EPF produces an EPF 
that, when run, mi^t produce an error message such as: 



Error: condition "ILLBGAI^_SBG^D$" raised at 41(3)A22722. 

(Referencing l(3)/0). 

ER! 



If you do not have access to the source code of the module, or if you 
wish to use a "quick fix",' relink the module and use the MAIN 
subcommand of BIND to specif/ the entrypoint of the module that is the 
main entrypoint of the program EPF. You may do this particularly 
quickly by using the following command sequence: 



BIND 

LORD failing-program.HJN 
MAIN main-entrypoint-name 
FILE working-program. BUN 



Restrictions on Writing PMA Modules for EPF Execution 

When writing a module in IWA for execution within an EPF, several 
restrictions must be dDserved: 

• Each subroutine in the module must execute in the V-mode or 
I-mode environment. 

• If the module has iitpjre procedure text, it must be declared as 
an impure module 

• If the module has pure procedure text, it d:iould be declared as 
a pure module 

• Subroutines within the module must not use explicit addressing 
to externals unless their addresses are explicitly set during 
the BIND session 

• Indirect Pointers (IPs) used in the module must never be 
modified by the module, because they are not necessarily 
reinitialized when the EPF is reinvoked 

This section discusses these restrictions. 
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mk Subroutines Must Execute in V-mode or I-mode Environment ; A PMA 
subroutine intended for execution within EPFs must be assembled in the 
V-mode or I-mode envirorment, as iirplied ty the requirements that IMA 
modules used for EPFs must begin with SEG or SEGR. 

Under most circumstances, a PMA module must execute entirely in V-mode 
or I-mode. Occasionally, it may enter R-mode or S-mode to execute a 
limited set of instructions. For example, it may wish to execute a PIO 
instruction to read or test for a character from the user terminal. 
However, the PMA subroutine must reenter V-mode or I-mode before 
returning to the calling parocedure. 

Impure fMA Module Restrictions ; If a PMA module is impure, the SEG or 
SBGR pseudo instruction at the tcp of the module must read SEG IMKIRE 
or SBGR IMH3RE. 

An inpure IWA module is characterized ty an inability to be executed 
with the pure procedure (EROC) portion of the subroutine protected 
against modification ty the subroutine. Instead, BIND places such a 
irodule in impure procedure (IMHJRE) segments of an EPF. An IMR3RE 
segnent is similar to a HIOC segment in that it contains procedure code 
and therefore must start at offset in an actual segment, whereas DATA 
segments are relocatable to anyvAiere inside a segment. However, an 
IMPURE segnent is not shared between users and is not protected against 
writing. Except in the case of a process-class library EPF, IMHJRE 
segments are treated like DATA segments by IRIMDS, in that they are 
reinitialized each time the EPF is invoked. 

An/ JMA module that explicitly stores into the pocedure text is 
inherently iiipure. Such modules are said to employ self-modifying 
code . This is widely regarded as poor programming practice. Moreover, 
some Prime systems employ preprocessors or a pipeline architecture, 
which may not behave as ejected under such circumstances. On Prime 
systems, therefore, self-modi^ing code may not work or may result in 
nontransportable programs. 

However, a IMA module can also implicitly modify procedure text, for 
example, by placing the ECB for the module in the procedure text and 
linking the module into an EPF. When such a module is part of an EPF, 
the actual placement of the linkage text is determined when the program 
is run, not when it is linked ty BIND. (When loading with SEG and 
producing SEG runf iles, the linkage text is placed during the loading 
of the program by SEG.) 

Therefore, when running as an EPF, ERIMDS must set the linkage base 
pointers for the ECB of each procedure in the EPF. If an ECB is in the 
procedure text, v^ich is normally protected against writing, IRIMDS 
would encounter an access violation error if it tried to set the 
linkage base pointer for that ECB; therefore, IRIMDS does not attanpt 
to modify the ECB. It is because the ECB requires modification at 
runtime that a module with an ECB in the procedure text is considered 
.impure. 
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If BIND encounters an ECB in the procedure text, and the module is not 
declared as an iirpure module, BIND issues a warning message. If the 
resulting EPF is executed, it may produce an access violation error 
when the offending module is invoked, because the imaginary address has 
not been translated into an actual address. 

Similarly, placing IPs (Indirect Pointers) in the procedure text 
results in an impure module when that module is linked using BIND, 
unless all such references identify external symbols that are 
explicitly located during prograni binding using the SYMBOL command of 
BIND. 

Modification of procedure text can occur explicitly or iirplicitly. An 
explicit modification is performed ty the subroutine code (or possibly 
code outside the subroutine) , When the subroutine is run within an 
EPF, implicit modifications occur when subroutine linkage data are 
placed in the procedure text. Biis linkage infcarmation must be 
dynamically adjusted by the EPF mechanism when the subroutine is 
executed. 

A JST (Jump and STore) instruction that references an internal 
subroutine also produces impure code, because JST stores the offset 
portion of the return address in the haliSi/ord that is the target of the 
instruction and then begins execution at the subsequent hal&?ord. If 
the target of the JST instruction is in procedure code, rather than 
linkage, common, or stack frsme storage, then the procedure code is 
inpare. Instead, use the JSXB, JSX, or JSY instructions, and modify 
the target subroutine accordingly. 

The RLIT and FIN pseudo instructions are often used to specify that 
literals are to be placed in the procedure text, rather than the 
linkage text. If literals are properly used, this does not result in 
an irtpire IMA module. However, using RLIT or FIN for literals that are 
to be stored into results in an iitpure module. (Storing into literals 
is considered extranely bad progrannming practice.) For example, the 
following literal reference is a pure reference independent of the use 
of RLIT or FIN: 



LEA =5 



However, the following literal reference requires that the RLIT or FIN 
pseudo instruction not be used if the procedure is to ranain pure: 



STA =10 



This reference also has the dangerous side effect of causing references 
to the literal value of 10 to reference a different value for the 
entire subroutine or for portions of that subroutine. 
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Pure EMA. Modules ; If a EMA module is pure, that is, if it does not 
have any of the characteristics of an iinpure module as described above, 
then the SBG or SEGR peeudo instruction at the top of the module should 
read SBG HJRE or SBGR HJRE. If RJRE is not specified, the default is 
HJRE anyway. 

However, explicitly including the PURE keyword can be a convenient 
signal to other programmers that the module has been checked for 
purity. If this convention is used, then any FMA module without a PURE 
or IMR3RE keyword following the SBG or SBGR pseudo instruction ^ould 
be checked for purity before being linked into an EPF. 

No Ei^licit Addressing of Eynamically Placed Externals ; If a PMA 

module attanapts to use an explicit address to an external entity, and 

the external entity is not placed via the SWBCL command during the 
BIND session, the PMA module may not execute properly. 

Such an attempt mi^t appear as follcws; 
LDA THEVALUE, * 



IHEVALUE OCT 4001 

OCT 174000 

TO reme^ this situation, either use the SYMBCL command to place the 
entity being addressed through IHEVALUE at 4001/174000, or fix THEVALUE 
to appear as follcws: 



EXT ENTITY 
THE7ALUE IP ENTITY 



Do Not Store Into IPs or ECBs ; If your program declares Indirect 
Pointers (IPs) or Entry Control Blocks (ECBs) , it should never modify 
them during. execution. For example, consider the following subroutine; 



SBG 

RLIT 

SYML 
* 

EKT TESTSUBR 

* 

LINK 

TESTSUBR BCB SIPRI 

HROC 
* 

START CALL TMXJ 
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■k 


AP 
AP 


THE_IPf *S 
=16rSL 


* 


EAL 
STL 


yiKIN32 
THE-IP 


* 


PKm 




STRINGl 

yi'RING2 
* 


BCI 
BCI 


"ffllS IS STRIN3 1' 
•THIS IS STRIN3 2' 


TOELIP 
* 


LINK 
IP 


S'i'RINSl 




END 


TESTSUBR 



This program uses raELIP to point to one of two strings. It specifies 
that, initially, THE-IP is to point to S1RIN31, and that for all 
subsequent calls, THE-IP is to point to S1RINa2. The intention here is 
for the subroutine to behave differently during its first invocation by 
a program than it behaves during subsequent invocations by the program. 

However, once IHE-IP is modified, it is not reinitialized fcy PRIM3S 
during repeated invocations of the program unless the program has been 
removed from memory (or if the k$init_all key is sujplied to EPF$INIT 
ty a user program as described in Volume III of this series) . 

For example, if you call this subroutine from a program that simply 
calls TESTSUBR once and then exits, then the program does not produce 
identical results when invoked several tines in a row, as shown in the 
following sample session: 



OK, RESUIVE TESTFROG 

THIS IS STRING 1 

OK, RESU^E TESTETIOG 

THIS IS STRING 2 

OK, RESUME TESTPROG 

THIS IS STRING 2 

OK, RE3yDVE_EPF TESTPROG 

OK, RESU^E TESTFROG 

1HIS IS STRING 1 

OK, RESUME TESTFROG 

THIS IS STRING 2 

OK, 



The REMDVELEPF command, used midway throuc^ this session, removed the 
EPF frcm memory. This forced the complete reinitialization of the EPF 
at the next RESU^E command, and thus restored IHE-IP to its initial 
state. 
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In any situation where you wish to modi^ IPs or ECBs, split them into: 

• The desired initial value (IP or ECB) that is not modified by 
the program 

• A block of linkage data (using the BSS pseudo instruction) that 
is to contain the actual value that is used and modified (BSS 2 
for IP, BSS '20 for ECB) during program execution 

Then, create another linkage-resident variable called FIRST_INVOCAT]DN 
and declared as follcws: 



FIRSr_INVOCATDN OCT 1 



Having done this, the first thing your subroutine should do is examine 
FIRST_INVOCAT]DN. If nonzero, it should initialize the block of 
linkage data described above to the desired initial value (IP or ECB) . 

Then, before your subroutine returns, it ^ould examine 
FIRST_INV0CAT1DN again, and, if nonzero, it should update the block of 
linkage data as desired and then set FIRSr_INVOCATIDN to 0. 

Because FIRST_INVOCAT]DN is an initialized datum, it is reinitialized 
by ERIMDS during every program invocation. 

Here is the TESTSUBR subroutine, ^own above, modified according to 
these recommendations: 



* 


SBG 

RLIT 

SYML 




If 


ENT 


TESTSUBR 


TESnSUBR 
* 


LINK 

ECB 

IROC 


START 


START 
* 


LEA 
BBQ 


FIRST_INV0CAT3DN 
GO 


K 


EAL 
STL 


OHELIP-INITIAL,* 
THEJP 


GO 

* 


CALL 

AP 

AP 


TNOU 

THE-IPf *S 
=16, SL 




T,rA 
BEQ 


FIRSr_INVOCATnDN 
RETURN 
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It 


EAL 
STL 


STRIN32 
TOELIP 


* 


CRA 
STA 


fiRST_INVOCAT]DN 


RL'iURN 


iKiN 




STRINGl 

yiRI]SG2 
* 


BCI 
BCI 


•mis IS S-iKINS 1' 
"IHIB IS ymiNG 2' 



LINK 

THELIP-INITIAL IP STRIN31 

IHELIP BSS 2 

FIRSr_INVOCATnDN OCT 1 
* 

END TESTSUBR 



New, invoking the TESTFROG progran linked with the new version of 
TESTSUBR shown above produces the correct output during subsequent 
invocations: 



OK, RESUME TESTPROG 
THIS IS STRING 1 
OK, RESUME TESTTROG 
THIS IS STRIN3 1 
OK, RESUME TESTPROG 
THIS IS STRING 1 
OK, 
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Shared Data 



The arcihitec±ure of Prine 50-Series systems allcws programs to have 
access to monory that is shared fcy all processes on a syston. 
Cooperating programs may use this capability to ooraniunicate betweei 
user processes. 

In addition, programs may wish to communicate with each other within 
the context of a single process, by accessing a predefined common area 
in nonshared (per-user) memory. 

The distinction here is beta(?een data that is shared for an entire 
system and data that is shared within a user process. Aside from the 
choice betweoi system-wide and process-wide ^ared data, the mechanisms 
used in employing both kinds of shared data access are the same; 
exceptions are noted in this chapter. 

This chapter describes: 

• How to define a shared common area in either shared or nondiared 
memory 

• How to update information in a shared common area atcmically 
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HOW TO DEFINE A SHARED OOMfON AREA 

There are two general w^s to define a cjommon area that is ^ared 
iDet>7een two or more programs, either within the context of one process 
(when nondiared memory is used) or of one systan (when shared memory is 
used) : 

• Use the SYMBOL subcommand of BIND to specify the actual address 
of an external common area 

• Place subroutines that wish to comnonunicate with each other in a 
process-class library EPF 

This section describes both approaches. 



Using the SYMBOL Subcommand of BIND 

The SYMBOL subcomnand of BIND is used to specify the actual address of 
an external common area in memory. This address may be either in 
shared memory or in nonshared static memory. 

Each program or library that wishes to use the i^ared area must use the 
SYMBOL subcommand during the linking of that program. In addition, 
they must all specify the same actual address of the shared data area. 
The name of the shared data area may differ from program to program; 
however, it is good practice to use the same name throughout. 

Because the location of tiie shared common area is placed during the 
linking of a program, there are no special requirements on the 
compiling of tiie program. However, there are coding requirements that 
are described in the section later in this chapter entitled HOW TO 
UPDATE SHARED INF0RMAT3DN ATOMICALLY . 

Before you can run a program that accesses a i^ared data, area, you 
must: 

1. Determine the address of the shared data area. 

2. Ensure that the shared data is initialized once during each 
system coldstart (for data in shared memory) or once for each 
user login (for data in nonshared memory) . 

3. Specify the appropriate SYMBOL subcommand while linking your 
program or library. 



Determining the Address of the Shared Data Area ; Because memory 
accessed via the SYMBOL subcommand of BIND is not managed by PRIMDS, 
you must determine a location for your shared data area that does not 
conflict with other programs or libraries. 
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For ^ared (system-wide) memory, you use shared segments. Shared 
segment numbers range from '2000 through '2577 at Rev. 19,4. However, 
you must consult with your System Adninistrator before deciding what 
portions of shared system-wide memory to use. He or she will use tiie 
System Administrator's Guide , which contains a list of ^ared segment 
usage by Prime products, along with information on shared segment usage 
at your installation, to determine where your diared data can be 
placed. 

For nondiared (per-user) memory, you use static segments. Static 
segment numbers range from '4000 i:^ to the first dynamic segment number 
for each particular user. You may, for example, use memory in segment 
'4001. However, bear in mind that static-mode programs use segment 
'4000 and may use static segnents beyond segment '4000. In addition, 
other users may be building programs which, like yours, use static 
segments to store shared per-user data; their choice of placonent of 
the data mi^t conflict with your dioice. Again, it is best to consult 
your System Administrator on the matter. He or she may decide to keep 
a registry of static per-user segment allocation at your installation. 

Ensuring That the Data Is Initialized ; Before any program uses the 
shared data, Eie data must be initialized, either by a program that 
uses the data or by a special initialization program. The execution of 
a progran, whether an EPF or a static-mode program, does not 
automatically cause common data placed via a SYMBOL sutxx>mmand to be 
initialized. This is because BIND cannot statically initialize a 
static segment, nor does IRIMDS perform any static segment 
initialization while preparing to execute an EPF. 

For shared (system-wide) memory, this initialization must be performed 
at the supervisor terminal; typically, it is performed at system 
ooldstart. The following sample command sequence may be entered 
interactively at the supervisor terminal or placed in the system 
startup file, HIIMDS.CDMI (or CLIWC) : 



OERERI 1 /* Allow SHARE commands, 

SHARE 2030 700 /* Share segment 2030 for read and write access, 
RESUME SYSTEM>INrr_MypROG /* Initialize segnent 2030. 
OHIIRI /* Disallow SHARE commands. 



Alternatively, if the initialization can be placed in a static-mode 
memory image, such as one generated via the SHARE subcommand of SEG, 
you can use a command sequence such as: 



OPRERI 1 /* Allow SHARE commands. 

SHARE SYSTEM>MyPROG2030 2030 700 /* Share segment 2030 for read 

/* and write access, and load a static-mode manory image into 

/* it. 
OERIRI /* Disallow SiPRE commands. 
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In both cases, you must build either the initialization program or the 
initialization static-mode shared image. 



Note 

If you SHARE a new shared segment without specifying a 
static-mode memory image to be placed in it, the data in the 
segment is initialized to all zeroes. You may therefore 
actually consider not initializing the segnent data at system 
ooldstart, and choose instead to have your program initialize 
the data area if a special portion of it consists of zeroes 
(indicating that the data has not yet been initialized) . If 
you do this, read the explanation belcw of how to perform 
initialization in this fashion, because this method is often 
used for nonshared (per-user) memory. 

For nondiared (per-user) memory, the safest approach to initializing 
your data area is to ask all users who are going to use your program or 
library to modify their LOGIN.CEL or LOGIN.GOMI file to include a 
ooraraand such as: 



RESUME rROG_J)IR>INrLJiraROG /* Initialize some static memory. 

You must build the INITJ«YIROG program and place it in the appropriate 
directory (rRCG_J)IR in the example) . 

This method is the safest because it reduces the chances that your 
program will be run before the data is initialized. 

An alternate method is for your program to determine, when it begins 
running, whether the data has been initialized, by testing a portion of 
the data area to see if it contains a certain data pattern. If it does 
not, your program can initialize it at that point in time, and set the 
data pattern to indicate that initialization has taken place. 

This kind of (^namic initialization has the advantage of being easier 
to set up, but it has the disadvantage of possibly not recognizing a 
situation where the correct data pattern is in place but the entire 
data area has not, in fact, been initialized. To reduce this risk, 
have your initialization logic write the pattern only after the rest of 
the data area has been initialized, and use plenty of unusual values in 
the data pattern. 

Specifying the ACT?ropriate SYMBOL Subcommand ; Specify the appropriate 
SYMBOL subcommand as f ollcws : """ 

SYMBOL name definition [size] 
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Here, name is the external name of the common area, definition is the 
location of the shared data area in the form segno/offset, and size , 
which is optional, specifies the size of the shared data area in 16 -bit 
hal&/ords (in decimal, not in octal) . For example, to specify that the 
external common area named MESSAGES is to be placed at address 2030/0 
and that it is 200 decimal halfwords in length, issue the following 
subcommand while linking the program via BIND: 



S^BQL MESSAGES 2030/0 200 



Using a Process-class Library EPF 

If you want to place the ^ared data area in nonshared (per-user) 
memory, it mi^t be best to place all subroutines that use the ^ared 
data area in a single process-class library EPF. Ihe data area may 
then be either a common area or the linkage for a single procedure that 
contains one or more entrypoints. This approach has the following 
advantages over using the SIMBOL subcommand: 

• BIND and IRIMDS ensure that the data area is autonatically 
initialized each time the process-class library EPF is first 
invoked by a user. 

• You do not need to check with your System Administrator to 
determine where, in static memory, to place the shared data 
area, because BIND and PRItDS determine the location of the area 
when the process-class library EPF is first invoked by a user. 

• You dD not need to specify any special BIND subcommand aside 
from the commands to declare the library to be process-class. 

• Additional memory may be allocated for the shared data area by 
using ALLOCATE statements in PLl/G. 

• Data can be initialized by using STATIC INITIAL (...) attributes 
in PLl/G or DATA /.../ statements in FORTRAN. 

However, you must ensure that the subroutines you place in the 
process-class library EPF meet the requiranents for a process-class 
library EPF, as outlined in Chapter 6. 

A small but illustrative example of this form of shared data access is 
the GET_USERNAME subroutine ^own in Chapter 6 and reproduced here: 



getjusername: proc returns(char(32)); 

del 1 timdat_info static, 
2 date char (6) , 
2 time fixed bin(15), 
2 ticks fixed bin(15). 
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2 meters (4) fixed bin(15), 
2 tps fixed bin (15) , 
2 user_number fixed bin(15), 
2 user_name diar(32); 

del have_info bit(l) static init('O'b); 

del timdat entry(l,2 char{6),2 fixed bin(15),2 fixed bin(15), 
2 (4) fixed bin(15),2 fixed bin(15),2 fixed bin(15), 
2 char (32) , fixed bin (15) ) ; 

if '^have_info 
then do; 

call timdat (tiindat_info, 2.8) ; 

have_info='l'b; 

end; 

return (use r_naine) ; 
end; 

Because the task of this subroutine is simply to return the username of 
the invoking user, it is written to save time after the first 
invocation by calling the TIMDAT subroutine, vAiidh is an internal 
ERIMDS entrypoint, only once. After the first call, subsequent 
invocations result simply in the returning of the username acquired 
during the first invocation. 

If GEIL.USERNAME is placed in a process-class library EPP, then several 
programs that call it may be run, and yet it will invoke TIMDAT only 
the first time it is run. miMDS keeps the linkage data for a 
process-class library EPF active between program invocations, as 
described in Chapter 6. 

In a sense, this subroutine "communicates" betweoi program invocations 
within a single user process. One program may have to end up calling 
TIM3AT via GET_USERNAME to acquire the username of the user, but the 
next program run by that user reuses the same username. This is a very 
simple form of interprogram communication. 

This single use of process-class library EPF linkage is applicable to 
information that is process-wide, rather than program-wide. Other 
examples of such information include: 

• User number 

• Terminal type — the user may have to be asked to enter the 
terminal type the first time, but after that, it could be made 
available to subsequent programs and libraries via a 
process-class library EPF subroutine 

• User's origin directory 
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• User's erase and kill characters (useful if the process-class 
library EPF also handles the collection of command lines; the 
internal HlirCS subroutine EEIKL$$ is already quite fast) 

More compOLex uses of process-class library EPF linkage (or common) data 
areas mi^t include: 

• Keeping track of virtual circuits a user has open to other 
systems for remote login or other purposes, allowing a user to 
leave a networking program and later reenter it v?hile keeping 
his or her connections intact 

• Keeping track of hew many times a user invoked one or more 
particular applications and possibly even keeping track of 
functions invoked within each application — a log file unit 
number mi^t be a candidate for a shared datum 

However, except for the very simplest uses of shared per-user data 
areas, you must be careful to design subroutines so that they either 
prevent interruption (such as fcy inhibiting quits or establishing 
on-units) or are robust enough to withstand interruption at ar^ point 
f ollcwed fcy a new invocation of the same or similar subroutines. 
Remember, a subsequent invocation of an executing subroutine in a 
process-class library EPF, while recursive in nature, never causes the 
allocation or initialization of linkage data; the existing linkage 
data is used. Modifications made fcy the second invocation of the 
subroutine can affect the ability of the first invocation of the 
subroutine to complete correctly vAien its execution is resumed. See 
the next section for information on how to update shared information in 
a manner that protects against multiple concurrent updates. 



HOW TO UfDATE SHARED INFORMATION A10MICALLY 

Whether in system-wide shared memory or in per-user nondiared manory, a 
data area must be protected against the possibility of multiple 
concurrent updates if: 

• Updates can be performed by two processes — only for 
system-wide shared manory 

• Updates can be performed by either two or more separate 
subroutines or two separate invocations of a single subroutine. 
Tliis occurs when one of the subroutines can be invoked following 
an interruption of one of the subroutines (such as via a user 
typing CDNTOCL-P or the asynchronous invocation of an on-unit as 
a result of a condition such as HLJjOGO$ or LOGaJT$ being 
signaled) 

Incorrect or nonexistent use of interlocking facilities for the 
updating of shared data areas is very difficult to detect; similarly, 
correct use is difficult to prove. Topically, incorrect or nonexistent 
use of such facilities results in perhaps a serious program error onoe 
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in a great while; because the serious error is not easily 
reproducible, it is often written off as a "glitch". To build the most 
robust product, you should carefully analyze portions of your product 
in which interlocking facilities might be needed to determine just how 
to use them. 

You should study how your subroutines use either the linkage area of a 
process-class library EPF or, more obviously, shared systatMtfide memory 
to see if interrupt inhibition or atomic updating are called for. Keep 
in mind that statanents such as 



ITEMS=rrEMS+l 

are interruptible between the reading of the current value of TTEMS and 
the storing of the incronented value. An interruption at that point, 
followed by reinvocation of the same subroutine, mi^t result in two 
invocations of the subroutine, causing the ITEMS value to be 
incremented only once. If ITEMS is used as a unique identifier ty 
subroutine invocations, the results mi^t be disastrous; yet this 
situation mi^t not ever occur even during exhaustive testing, and 
would probably not be reproducible. On the other hand, if the 
incranent of ITEMS is tested against seme other static data in an 
atomic fashion, perhaps the failure of the multiple concurrent update 
will not have a bad effect on the program. 

For example, see the final version of the AVERAGE subroutine in Chapter 
6. Note that while it makes reasonably heavy use of linkage (common) 
data, only certain updates to the common areas are protected by calling 
a special subroutine. Other updates are inter ruptable because they are 
protected hy the atonic updates performed, ultimately, ty the STAC 
instruction in the O0ND_STORE subroutine. 

Following is a listing of the OOND_STORE subroutine, written in FMA, 
plus a version of the subroutine named LCN:l.GOND_STORE that deals with 
FIXED BIN (31) (FULL INT, or INTBGER*4) integers. After that, a listing 
of a special-purpose FMA subroutine that performs a typical use of the 
STAC instruction, named INCITEMENT, is provided. 



Note 

These three subroutines, GOND_JSTORE, IONGI_OOND_£nDRE, and 
INCREMENT, are provided ty Prime only in this document, not on 
the master disk. If you wish to use than, you must key them 
into your system. They are all IMA subroutines. 
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The OOND_gPORE. H1A Subroutine 

The (X)ND_jSTORE.PMA subroutine is called with three halfi/ord integers, 
and returns as its function value a halfivord integer. In ELl/G, its 
calling sequence is: 



del oond_store entry(fixed bin{15) , fixed bin(15) rfixed bin(15)) 
returns(fixed bin{15)); 

cond_store_ok=cond_store (destination, newL_value, old_value) ; 



If cond-Storejok is 1, then the value of destination has been 
successfully changed from old_value to newL.value . Otherwise, 

oond_stor^ok is 0, and no change to destination has taken place. 



SEIG HJRE 

RLIT 

SYML 



* 

* 



SUBR CDND_STORE,ECB 



LINK 
E!CB ECB CDND_ST0RE,,WHERE,3 

PROC 

OONTLSIDRE EQU * 
ARGT 

LDA OLD,* 
T/B 

LDA NEW,* 
STPC WHERE, * 
BCBQ OK 
CRA 
IREN 

OK LT 

IRIN 
* 

DYNM WHERE(3) ,NEW(3) ,CLD(3) 
* 

END 
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The LCMG_OOND_STORE.PMA Subroutine 

The ljCNGLaOND_sroRE. FMA subroutine is called with three fullword 
integers, and returns as its function value a halfi*ord integer. In 
Hil/G, its calling sequence is: 



del long_oontl_store entry(fixed bin(31) , fixed bin(31), 
fixed bin(31)) returns(fixed bin(15)); 

oond_stor^ok=long_oond_store (destination, new_value, old_value) ; 



If oond_store_ok is 1, then the value of destination has been 
successfully changed from old-value to new_value . Otherwise, 

cond-Stoce_ok is 0, and no change to destination has taken place. 



SBG HJRE 

RLIT 

SWL 
* 

SUBR DC3NG_00ND_STORE,BCB 

LINK 
ECB BCB lJ3N3_a5ND.jSTORE,,VJHERE,3 

FROG 
* 

LONG_CDND_^roRE BQU * 
ARGT 

LDL OLD,* 
ILE 

LDL NEW,* 
STLC WHERE,* 
BCBQ OK 
CRA 
HON 

OK LT 

ERIN 

DYNM WHERE (3) ,NEW{3) ,CLD(3) 

END 



The INCREMENT. HIA Subroutine 

The INCREMENT. PMA subroutine increments the value of a variable 
atomically and returns the new value as its function value. It deals 
entirely in halfword integers (FIXED BIN (15), INTBGER*2, HALF INT). 
•Note that by the time the subroutine actually returns, the returned 
value may differ from the latest value of the variable due to an update 
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by another procedure or process; the purpose of the returned value is 
to provide the caller with a value guaranteed to be unique if all 
references to the variable ty all procedures and processes are done 
through the INCREMENT subroutine. 



SBG HJRE 

RLIT 

STML 
* 

SUBR INCRHyiENT,BCB 
* 

LINK 

ECB ECB INCREMENT, r VARIABLE, 1 

PROC 
* 

INCREMENT BQU * 

ARGT 
* 

TRY_?GKm LDA VARIABLE, * 

Tffi 

AlA 

STAC VARIABLE, * 

BCNE TRXJ^AIN 
* 

* It is iirportant to leave A-reg as is after the STAC 

* instruction succeeds ; do not LDA VARIABLE, * or it may 

* be different from what we incremented it to just new! 
* 

PRIN Ne* value in A-reg 

* 

DYNM VARIABLE (3) 
* 

END 
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Maps and Addresses 



Because EPFs are dimainically placed in available memory at runtime, 
maps of EPFs produced by BIND do not, for the most part, contain actual 
memory addresses. Instead, they contain imaginary addresses, as 
described in Chapter 1. 

Once an EPF has been mapped to memory, the location of its procedure 
code is determined; once that EPF has had its linkage data allocated, 
the location of all data in the EPF is determined. To display 
information on where code and data for an active or mapped EPF have 
been placed, use the following format of the LIST_EPF command: 



LISTEPF EPF-name -SEGMENTS 



You may then correlate the displayed output from the LISTLEPF command 
with the BIND map produced for that EPF to determine the actual 
addresses of subroutines, common areas, and so on, in that particular 
invocation of the EPF. 

Ihis chapter explains imaginary versus actual addresses. Then, this 
chapter describes how to use LIBTJI^ output, LIST_SBGNEMP output, BIND 
maps, VPSD, and DUMP_STft3K output to examine in-roemory EPFs. Finally, 
the chapter provides a ^ort section on expanded listings. 
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IMAGINARY VS. ACTUAL ADDRESSES 

To understand how to correlate BIND maps with the displayed output of 
PRIfCS commands such as LIST_EPF, DUMP_STft:K, and VPSD, you must first 
understand imaginary addresses and how they differ from actual 
addresses. 

An imaginary address is a temporary representation of a memory address 
generated ty BIND. An imaginary address identifies locations within an 
EPF for later correlation with actual addresses determined by HRIFDS 
when an EPF is mapped, its linkage allocated, and its linkage 
initialized. An actual address is also known, fron a system 
architecture point of view, as a virtual manory address. 

Both imaginary addresses and actual addresses have the form: 
segno/offset 



So that imaginary addresses and actual addresses can be distinguished 
at a glance, imaginary addresses have signed segnent numbers, vrtiile 
actual addresses have unsigned segnent numbers. Here are some sample 
addresses: 



Imaginary Addresses Actual Addresses 

-000V10472 4376/15433 

+0000/77160 4363/126021 

-0004/1672 4232/1000 

4O006/1000 4337A00123 

(The addresses listed above do not necessarily have any correlations 
with each other.) 

Sometimes, actual addresses are shown with ring numbers , as in 
4376(3) A5433 or 4337(0)/100123. These ring numbers have no effect on 
the execution or behavior of your program; therefore, you may ignore 
them. 

Also, different portions of BRIMDS and BIND display both types of 
address with or without leading zeroes. Therefore, imaginary address 
-000yi0472 may also be displayed as -2/10472 or as -000^/010472; all 
three displays are equivalent. 



Positive or Negative Segnent Numbers 

Imaginary addresses have signed segnent numbers; either a + or - 
always precedes the segnent number of an imaginary number. 
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• A positive (+) sign indicates a segnent used to hold pure 
procedure code. 

• A negative (-) sign indicates a segnent used to hold linkage or 
oonmion data, or iitpare procedure code. 

In addition, BIND maps indicate the type of information stored in each 
segment. In BIND maps, pure procedure segnents are labeled PROC; data 
segments containing linkage or common data are labeled DATA; and 
iirpure procedure code segnents are labeled IMHJRE. IROC segnent 
numbers always start with a positive (+) sign; DATA and IMHJRE segnent 
numbers always start with a negative (-) sign. 

Thus, imaginary segnent number +0 is a EROC (pure procedure) segnent, 
whereas imaginary segnent number -2 is an inpure segnent that may be 
either a DATA or an IMPURE segnent. 



USING IHE LIST_EPF COMMAND 

The LIST_EPF command is the crucial command to use when working with 
EPFs and memory addresses. It displays the correspondence between 
imaginary segnent numbers and actual memory addresses. 

For example, here is the display of a LIST_EPF -SEGMENTS command issued 
after the ID, OOPY, and DELETE commands have been used: 



OK, LIST.JPF -SEGMENTS 

1 Process-Class Library EPF. 

(active) <SYSDSK>LIBRARIES*>SYSTEliJiIBRARY.HJN 

2 procedure segnents: +0:4234 +2:4235 

2 linkage areas: -2:4376(0)/0 -4:4377(3)/730 

3 Program EPFs. 

(not active) <sysdskx:mdncoxx)py.fun 

1 procedure segment: 40:4237 

2 linkage areas: -2:4375 (0)/0 -4:4377(3)/44744 

(not ac±ive) <sysdskx:mdnco>delete.hjn 

1 procedure segnent: +0:4240 

2 linkage areas: -2:4374(0)/0 -4:4377 (3) /52770 

(not active) <sysdskx:mdnco>ld.fdn 

1 procedure segnent: +0:4236 

1 linkage area: -2:4377 (3) /36100 

OK, 
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Ihe oorresponttenoe between imaginary EROC segment numbers and actual 
addresses is displayed as: 

+iinagi na ry_segno : actual^segno 

The correspondence betweai imaginary DATA and IMHJRE segnent numbers 
and actual addresses is displayed as: 

-imaginary_segno:actua!L_segno/actual^offset 



Notice hew eadi EROC segnent (with RX access) has only one EPF listed 
for it in the LIST_JSBGMENT display; whereas segnent 4377, a DATA 
segnent, has four EPFs listed for it. This is because an imaginary 
EROC or IMPURE segnent must be the only resident of an actual segnent, 
even if it does not use all of it; iitaginary segments containing 
executable procedure code must be placed at offset of an actual 
segment because executable procedure code is not relocatable within a 
segment. However, imaginary DATA segnents can share actual segnents 
with other imaginary DATA segments, because they can be easily 
relocated within a segnent. 

Therefore, in the output from the LIBT_EPF -SEGMENTS command shown 
earlier in this section, the actual addresses for imaginary EROC 
segments are shewn without offset portions, as in: 



+0:4240 (a HIOC segnent) 



The actual addresses for imaginary DATA segnents are shown with nonzero 
offset portions, as in: 



-4:4377(3)752770 (a DATA segnent) 



For EPFs containing imaginary IMEURE segments, LISTJEPF -SEGMENTS 
displays the actual addresses with zero offset portions, as in: 



-2:4374(0)70 (an IMEURE segnent) 



Note 

The L]BT_JI>F -SEGMENTS command displays information on only the 
most recent invocation of an EPF, Previous active invocations, 
applicable for program EPFs and program-class library EPFs, are 
not displayed in the list of linkage segnents. 
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USnC THE LISaLSEGMEHOT OOMMfiND 

Tto illustrate the actual mapping of segnents for the EPFs displayed in 
the sample LISTJ3*F display above, here is the display from a 
LIST_SE)G^ENT -NME oomnand issued just after the same LIST_JI>F 
-SEGMENTS command shown above: 



1 Private static segment, 
segment access 



4000 MX 



9 Private dynamic segments, 
segment access epf 



4234 


RX 


4235 


RX 


4236 


RX 


4237 


RX 


4240 


RX 


4374 


mx 


4375 


IWX 


4376 


mx 


4377 


IWX 



<SYSDSK>LIBRfiRIES*>SYSTEIlJ.IBRfiRy. HJN 
<SYSDSK>LIBRfiRIES*>SYSTElULIBRfiRY. PUN 

<sysdskx:mdnco>ld. hjn 
<sysdskx:mdncoxx)py, hjn 
<sysdskx:mdncx)>delete. hjn 
<sysdskx:mdnco>delete. hjn 
<sysdskx;mdncoxx)py. fun 

<SYSDSK>LIBRfiRIES*>SYSTE3yLLIBRARY. HJN 

<sysdskx:ndncoxx)py. hjn 
<sysdskx:mdnco>delete. hjn 
<sysdskx:mdnco>ld. run 

<SYSDSK>LIBRfiRIES*>SYSTEMJiIBRARY. HJN 



OK, 



"The segments with RX access are PROC segments — the R indicates that 
they may be read, v*ile the absence of the W indicates that they cannot 
be written. The segnents with access FWX can be both read and written; 
they are either DATA or IMHIRE segnents. As ej?)lained in Chapter 1, 
IRIMDS automatically shares PROC segments befcweei users using the same 
EPF. 



USING TOE BIND MAP 

TJie map produced fcy a MAP subcommand while in BIND shows the 
relationdiip of locations internal to an EPF to the beginning of two or 
more imaginary segnents that are used by that EPF. Each EPF has at 
least two segments: a PROC segnent and a DATA segnent. Larger EPFs 
may use more than one HIOC or DATA segnent each, and some EPFs have 
IMHJRE segments (which are like VRCC segments except they are modified 
during execution and hence cannot be shared or protected against 
modification) . 

• The BIND map primarily contains imaginary addresses. The exceptions 
occur when the SYMBOL subcommand is used to specify an actual address 
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for an external symbol (such as a cxsmmon block) . In this case, the map 
shows an actual a6c3ress (with an unsigned segnent number) for that 
symbol, and the list of segnents at the top of the map show that 
segment as a STATIC type segnent. 

Once you have begun executing an EPF, its imaginary addresses have been 
resolved to actual addresses. You can then use the LIST_EPF -SEGMEMS 
command to display the mapping from imaginary segnent numbers in the 
BIND map to actual addresses in user memory. You can then add the 
offset portion of a syiitool's imaginary address to its corresponding 
actual address in the LIST_EPF display to determine the symbol's actual 
address in user memory. 

For example, suppose a line in a BIND map reads : 



Name ECB address Initial IB% . . , Initial IB% 

SUBRl -000^000004 +0000/001005 . . . -000^177400 

Also, suppose a LIST_EPF -SEGMENTS command displays the following 
information for the EPF containing SUBRl: 



(active) <USRDSK>UN3ER>My_PR0G.HJN 
1 procedure segnent: +0:4234 
1 linkage area: -2:4377(3)/730 



Determining Procedure Code Addresses 

To determine the address of the first instruction of SUBRl, you first 
examine the imaginary address in the column labeled Initial EB%. Here, 
the imaginary address is +0000/001005. Next, you look up imaginary 
segment +0 in the LIST_EPF display to determine its corresponaing 
segnent number. Here, +0 corresponds to segnent 4234. Therefore, the 
actual address for the first executable instruction in SUBRl is 
4234/1005. 



Determining ECB Addresses 

To determine the address of the ECB of SUBRl, you examine the imagirary 
address in the column labeled ECB address. Here, the imaginary address 
is -000^000004. Next, you look up imaginary segnent -2 in the 
LIST_EPF display to determine its corresponding segnent number. Here, 
-2 corresponds to actual address 4377/730. You add 730 to 4 (without 
ever carrying into the segnent number portion) to determine the actual 
address of the ECB for SUBRl, 4377/734. 
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Detennining Stack Frame Addresses 

To determine the address of a stack frame for an active procedure, use 
the DUMP_STACK command, described later in this chapter. 



Determining Addresses For Other Map Objects 

To determine the address of other objects in a BIND map, such as common 
blocks, dynamic links, and so on, simply use the same method used for 
determining procedure code addresses (when a positive imaginary segnent 
number is involved) or for determining ECB addresses (when a negative 
imaginary segment number is involved) . . 

However, for link frame addresses, read the next section carefully 
before proceeding. 



Determining Link Frame Addresses 

Finally, let's look at the trickiest calculation. To determine the 
address of the link frame of SUBRl, you examine the imaginary address 
in the column labeled Initial IB%. Here, the imaginary address is 
-000V177400. However, this is not the imagirary address of the link 
frame itself; it is, as implied by the column header, the address 
placed in the Link Base (IB) when the procedure is called. On Prime 
systons, the address in the IB is always the starting address of the 
link frame minus '400 (in halJ6«?ords, without borrowing from the segnent 
number portion) . 

Tlierefore, v*ien considering the link frane, you must decide whether you 
wish to determine the address of the beginning of the link frame itself 
or the address placed in the IB when the procedure is executed. The 
address of the link frame is useful when you want to examine the link 
frame data. "nie address placed in the IB is useful when you want to 
examine procedure code that uses the link frame, because assembler 
instructions include the '400 hal&^ord offset; the instruction LDA 
IB%+'400 references the first halfword in the link frame. 

In fact, determining both values is strai^tforward. As before, 
imaginary segnent -2 corresponds to address 4377/730, so you add 730 to 
177400 (without carrying) to determine the address placed in the IB for 
the SUBRL procedure, 4377/330. To determine the actual address of the 
beginning of the link frame for a procedure, add '400 to the IB for the 
procedure (again, without carrying into the segnent number) . Here, tiie 
beginning of the link frame for SUBRl is 4377/730. 

IRIMDS ctanmands that display memory allocation information, such as 
LIST_EPF, display link frame addresses. PRItCS commands that display 
base register and instruction information, such as DUMP_jSTACK, VPSD, 
•and PM, displ^ IB addresses, v^ich are '400 less than the actual 
locations of corresponding link frames. 
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USIN3 VBSD 

When you use VESD (Virtual Prime Symbolic Debugger) , the arithmetic is 
handled by the computer. The method for accessing a particular 
location in mamory, given its imaginary address and the actual 
addressing corresponding to the imaginary segnent number, is: 



SN actual-segment-number 
RE actual-offset 
A >imaginary-offset 



In VE5D, the SN subcommand sets the segnent number; the RE subcommand 
sets the relocatable address offset, which is particularly useful for 
this sort of job; the A subcommand accesses (opens) a memory location, 
and the > specifies that the value following the > is to be treated as 
relative to the value specified in the RE subcommand. 

For example, to access the ECB for SUBRl, which is at imaginary address 
-000^000004 and where imaginary segnent -2 corresponds to actual 
address 4377/730, you would issue the following VPSD subcommands : 



SN 4377 
RE 730 
A >4 



For addresses in EROC or IMHJRE segnents, vAiich always have an 
actual-offset ot 0, the method is even simpler: 



SN actual-segnent-number 
A imaginary-offset 



For example, to access the first executable instruction in SUBRl, which 
begins at imaginary address +0000/001005, and where imaginary segnent 
+0 corresponds to actual segnent 4234, you would issue these VPSD 
subcommands: 



SN 4234 
A 1005 



To set up the IB register to access the link frame for a particular 
procedure, given the imaginary address from the Initial IB% column of 
the BIND map and the corresponding actual segnent number from the 
LISTJEF oomnand display, use the following method: 



LB actual-segnent-number actual-offset+imaginary-offset 
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The IB subcoiranand of VESD sets up an internal representation of tiie IB 
register, used when you make IB-relative references in VPSD (such as by 
typing something like A IB%+10) . Ihree other similar coinrtands, IB, SB, 
and XB, set up the internal copies of the other three base registers 
for the same purpose. (The + is underlined to distinguidi it from 
dashes in the variable names; you type in the + as shown, hut you 
substitute actual values for the variable names.) 

For example, to set up the IB for the SUBRl procedure, whose imaginary 
IB address is -000^177400 and where imaginary segment -2 corresponds 
to actual address 4377/730, you would issue these VPSD subcommands : 



IB 4377 730+177400 

You would then reference the first halfword of the link franae of SUBRl 
by typing: 

A IB%+400 



USING 1HE IXJMP_J3TACK COMMAND 

llie IUMP_^ACK command is necessary for displaying the addresses of 
stack frames in your program. Because it displays all of the stack 
frames between the latest frame and the initial frame at command level 
1, identification of which frame is the desired frame is not 
necessarily strai^tf orward, Ihere are two ways to identify the proper 
stack frame; 

• By the Owner= label, if the procedure you are attempting to 
locate is writtai in PLl/G, F77, VRPG, or Pascal 

• By comparing the (IB= ) field to the LISTLEPF -SEGMENTS display, 
and then to the BIND map of the appropriate EPF, which works for 
a procedure written in ary language 

The first method requires that the procedure identify itself ty setting 
up its stack frame header so that it identifies its ECB, and ty having 
the ECB contain the name of the procedure. Hcwever, not all Prime 
language translators generate code to perform this action each time a 
procedure is invoked; for example, ETO and PMA do not perform the 
requisite actions. In such cases, you must compare IB values. 

Typically, you are searching for the stack frame of a particular 
procedure. In this case, determine the Initial IB% for the procedure 
according to the instructions given earlier in this chapter. Then, 
look for the corresponding stack frame in a ECMP_STiiCK displ^. If it 
isn't there, it means that the procedure you are searching for is not 
active and therefore not on the stack. 
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How to Locate the Stack Frame for a Procedure 

Here is a sample display from the D[JMP_ffrACK command after a user 
interrupted a running program EPF by typing OMIRCL-P: 



OK, DUMP_J5TACK 

Backward trace of stack from frame 7 at 6002(3) /4046. 

STACK SBGMEMP IS 6002. 

(7) 004046: CONDITION FRAtE for "QUIT$"; returns to 13(3)/77622. 
Condition raised at 4257(3)A327; IB= 4377(0)/44424, Key&= 004000 

(8) 003726: FAULT ETyVTE; fault type "RXM" (0) 

Fault returns to 4257(3)A327; IB= 4377(0)/44424, keys= 004000 
Fault code= 000000, fault addr= 4257(3)/130004. 
Registers at time of fault: 

Save Mask= 007755; XB= 4257{3)/1042 



GRD 60013 24667 


14002624667 GRl 





L,GR2 12 


12 E,GR3 310 


11766 62011766 


GR4 


Y,GR5 


174052 174052 


GR6 3466 66002 


715466002 X,GR7 


1061 1061 


FARO 4375 (3) A2 


FLRO 13 FRO 


2.41041274E-39 


FARl 4377 (3) /124 


FLRl 3466002 FRl 


3.75089893E 543 



(9) 003710: Owner= (LB= 4377(0)/44424) . 

Called from 4234(3)A055; returns to 4234(3)A061. 

(10) 003616: Owner= SUBRl (IB= 4377(0) A77460) . 
Called from 41(3)A25336; returns to 41(3)A25340. 

(11) 003462: Owner= (IB= 41(0)A25010) . 

Called from 13(3)A7354; returns to 13(3)A7376. 
Proceed to this activation is prdiibited. 

(12) 002220: Owner= (LB= 13(0)/20256) . 

Called from 13(3)A5025; returns to 13(3)A5033. 

(13) 001420: Owner= (IB= 13(0)/20256) . 

Called from 13(3)/7224; returns to 13(3)/7236. 

(14) 000640: Owner= (IB= 13(0)A1206). 

Called from 13(3)A63464; returns to 13(3)A63470. 

(15) 000632: Owner= (LB= 13(0)A63102) . 
Called from 4(0)A63466; returns to 4(0)/0. 

OK, 



In this example, the stack frames for the user's progran are numbers 

(9) and (10) . nhey are easily distinguished because the IB segnent 

•numbers are in the private per-user segnent range (4377 in this 

example) , rather than in public shared ERI^DS segnents (41 and B in 
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this example) . In addition. Frame (10) is easily identified as 
belonging to a procedure named SUBRl because it is a PLl/G procedure 
that identifies itself by name. The stack frame for SUBPl is 
600^3616, v^ere 6002 is the stack root (as displayed at the beginning 
of the DUMP_STACK displcQ^) ; the stack frame for the FMA subroutine it 
called, from which the QUrr$ condition was signaled via a user t^^ing 
OOmROL-P, is 6002/3710. 

However, in more compLicated situations, the stack frames are often not 
so easy to identify, so comparison against the IB registers displaced 
for each frane are helpful. 



Multiple Entrypoints With the Same IB 

In a situation where more than one entrypoint has the same IB, 
identification by IB is insufficient. Here, identification by ECB is 
required. To do this, examine the stack frame to determine the address 
of the calling instruction. Then, examine the next hi^er-numbered 
stack frame to determine the contents of the SB and IB registers for 
the calling procedure. Then, enter VPSD and examine the calling 
instruction to determine the address of the ECB. Often, the calling 
instruction is a iCL instruction that goes indirect through an IP in 
the link frame (IB-relative) ; if this is the case, you must also set 
up the IB in VPSD to be the IB for the calling procedure. 
Occasionally, the calling instruction is a PCL through an SB-relative 
IP, in which case you must set up the SB in VPSD accordingly. 

However, if the VCL is XB- relative, tracking down the actual address 
can be very difficult because tiie XB register contents can be changed 
during the processing of argument tonplates (APs) and its contents at 
the time of the call are not saved by the PCL mechaniam. In this case, 
your best bet is to backtrack throu^ the code prior to the PCL to 
determine how it calculated the address for XB by looking for an EAXB 
that is SB-, IB-, or IB-relative, and then reconstruct the sequence of 
instructions to determine the actual XB contents used at the time of 
the call. 

Example ; For example, to determine the address of the BCB that 
corresponds to the SUBPl procedure. Frame (10) in the above example, we 
first examine the display for Frame (10) : 

(10) 003616: Owner= SUBRl (IB= 4377(0)A77460) . 

Called from 41(3)/125336; returns to 41(3)A25340. 

This tells us that the instruction that called the SUBRl procedure is 
at address 41/125336. 
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Next, we look at the nejct frame. Frame (11) : 



(11) 003462: Owner= (IB= 41(0)A25010) . 

Called from 13(3)/17354; returns to 13(3)A7376. 

This tells us that the SB for the calling procedure is 600V3462 and 
the IB for it is 41/125010. Now, we enter VPSD, examine the calling 
instruction, and track down its IP to the ECB, Once we have the actual 
ECB address, we use LIST_J5BG^ENT to show us which EPFs have linkage 
data in that segment; we then use LIsaLJI>F -SEJGFENTS on the most 
likely EPF in the LIBT_SEG^ENT display to determine whether there is a 
matchup between the ECB address, the actual address of the linkage data 
for the EPF, and the imaginary ECB address in the BIND map. 

OK, VPSD 

$SN 41 

$A 125336 ;S 

41/ 125336 PCL% SB%+ 107,* / 

$SB 6002 3462 

$A SB%+107:O 

600y 3571 4377 (CR) 

600V 3572 7050 /^ 

$Q 

OK, LIST_SEG^ENT 4377 -NAfC 

1 Private ^mamic segment, 
segment access epf 

4377 MX <USRDSK>UN3ER>MXLIBRfiRy.FUN 

<SYSDSK>LIBRARIES*>SYSTEItJ,IBPARY. HJN 
<USRDSK>UN3ER>MXJRCG. HJN 

OK, LIST_EPF tCLJROG -SEGfENTS 

1 Program EPF. 

(active) <USRDSK>U^GER>My_HlOG.IUN 

1 procedure segment: +0:4235 
1 linkage area: -2:4377 (3) /7044 

OK, 



"She difference between an actual ECB address of 4377/7050 and an actual 
linkage data address of 4377/7044 is 4, yielding a corresponding 
imaginary ECB address of -2/4, or -0002/000004 as shown in the examples 
of SUBKL earlier in this chapter. 
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Examining the Stack Frame for a Procedure Invocation 

Once you know the address of a stack frame for a particular procedure 
invocation, you can reenter VISD and examine the stack frame by issuing 
the follcwing commands: 



VESD 

SB stackroot offset 

A SB%+n 



Here, stackroot is the segment number of the stack root, dispi^ed ty 
EUMPJSTACK at the top of its display and subsequently during the 
display if the stack switches to anotiier segment. (Watch for the STACK 
SEGIENT IS messages during the display; use the most recent message 
displayed befcare the target stack frane.) 

The offset value comes from the octal number follcwing the stack frame 
number. In the above D[JMP_STiO( example, the offset value for Frame 
(10) is 3616. 



USING EXPANEED LISTINGS 

Prime language translators all have the ability to produce expanded 
listings. An es^anded listing is a special type of listing, obtained 
by including the -EXPLIST option on the oranpiler command lir>e, that 
shows the partially processed machine instructions generated as a 
result of compiling each line in the source file, along with the offset 
of each instruction from the beginning of the program. However, there 
are several different formats of expanded listing output, and the 
offset values differ in meaning, such as between PTN and PLIG. Consult 
the language manual appropriate for your compiler for more information. 

The listings produced by IMA correspond, of course, to instructions in 
the source program. The offsets shown are from the beginning of the 
procedure code, the link frame, the stack frame, and so on. 
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Binary Editors 



•Hiis ciiapter describes the Binary Editor (EEB) and the Library Editor 
(LIBEEB) . EEB is used to cxeate and modify object (.BIN) library 
files. LIBEEB is used once a library is created to decrease linking or 
loading tine. Both of these programs operate on object text blocks 
generated by Prime language translators such as F77, ETO, CBL, PLIG, 
PMA, and so on. These object-text blocks form the input to BIND, IDAD 
and SEG. Tlie term linker is used to identify all three programs. 



LIBEEB 

The LIBEEB progran is used for editing bypass infcarmation into library 
files. The linker uses the bypass information to skip an unnecessary 
routine efficiently instead of reading and discarding all the unwanted 
object text. Depending on the size and number of unnecessary routines 
in a library, the linker may process library files up to 50 percent 
faster if they have first been processed by LIBEEB. 

LIBEEB is maintained as the runfile LIBEEB. SAVE in the UFD LIB. It 
should be used on a library file after its creation and after eadi time 
that the library is edited with the Binary Editor. The linker is 
capable, however, of handling a library which is not, or is only 
partially, processed by LIBEEB. 
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Because it is e:q»cted that LIBECB will be used fairly infrequently, 
the user/computer interaction is self-e3q)lanatca:y. LXBEEB asks for an 
input and output filename and for file type. In theory, a library with 
large routines will link faster if it is created as a Direct Access 
Method (DAM) file. In practice, none of the regularly used libraries 
contain routines large enou^ to warrant creating the library as a DAM 
file instead of as a Sequential Access Method (SAM) file. 



ECB 

The OOTimand format for EEB is: 



ECB 



input-file 
-ASR 
-PER 



[output-file] 



Both the input and output file may be pathnames. The input file diould 
be an existing library or the birary output of a Prime language 
translator. "Hie output file is optional; if specified, a file of that 
name is created if none exists. -ASR or -PTR instead of a file on the 
command line specifies a user terminal or paper-tape reader/punch, 
respectively. If tiiese are not included, a IRI^DS file is assumed. 
(-ASR and -PER are tremendously obsolete options.) 

EEB displays ENTER, and then waits for user commands. 



Operation 

EEB maintains a pointer to the input file. When EEB is initialized, or 
after a TOP or NEWINF subcommand, the pointer is at the top of the 
input file. Tlie pointer can be moved by the FIND subcomrrand to the 
start of a module. A module is identified fcy its subprogram or 
entry-point name. After a COPY subcommand (which copies blocks from 
the input to output file) , the pointer is positioned to the module 
following the module copied. 
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Subcxammand Summary 

EDB responds to the following subcommands, listed in aljiiabetical 
order. Subcommands may be at±>reviated to the underlined letters. 



Note 

The keyword ALL, used in the COPY and FIND subcommands, is not 
specially treated by EEB; if the external symbol name ALL is 
encountered in the input file, the COPY or FIND operation is 
terminated. This distinction is iicportant only for input files 
that contain an external syntol name of ALL; in such a case, 
use some random name instead of ALL to COPY or FIND all modules 
in an input file, such as FDSA. The ALL keyword is essentially 
an ad hoc standard. 



^ BRIEF 

Inhibits the display of subroutine names and entrypoints as they are 
encountered in the input file. (See also TERSE and VERIFY.) 



Cr>PY 



Copies to the output file all main programs and subroutines from the 
pointer up to (but not including) the subroutine called name or 
containing name as an entrypoint. If name is not encountered or if 
ODPY ALL is specified, EEB copies to the end of the input file and 
displays .BOTDCM. en the terminal. EEB moves the pointer past the 
last copied item. 

<RFL> and <SFL> are special keywords that search for a reset-force-load 
or set- force-load flag block. 






name 


FIND 


ALL 




<RFL> 




<SFL> ) 



Moves the pointer up to the module of the input file containing a 
subroutine called name or containing name as an entrypoint without 
copying the intervening modules to the output file. If name is not 
found, EEB moves the pointer to the end of the input file an3 SispLays 
.BOTTCM. on the terminal. 
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In VERIFY mode, the FIND ALL cx>inmand is useful for displaying all 
subroutines and entry names in the input file. 

<RFL> and <SFL> are special keywords that search for a reset-foroe-load 
or set-foroe-load flag block. 



► BISERT pathname 

Copies all modules of pathname to the output file. Ohe pointer to the 
original input file is unchanged. 



► j^INF pathname 

Closes the current input file and opens pathname as the new input file. 
■Hie pointer is positioned to the beginning of pathname . 



Closes the current output file and opens pathname as the new output 
file. 



► QUrr 

Closes all files and exits to ERIM3S. 

► REPLM: name pathname 

Replaces the object module containing name as an entrypoint by all 
modules of pathname . 

► RH. 

Writes a reset-foroe-load flag block to the output file. T/pically, 
all libraries begin with an RFL. The RFL block places a linker in 
library mode; while in library mode, only those modules that are 
referenced are linked. RFL mode is in effect until the linker 
encounters an SFL block. 
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Note 

Because an RFL block affects other files linked after the 
object file containing the RFL block, it is iirportant that any 
object file containing an REL block contain an SFL block at the 
end of the file. See the SFL crannand. 



► SEL 

Writes a set-force-load flag block to the output file. This block 
places a linker in force-load mode; all subsequent modules are linked, 
whether or not they are called. SFL mode is in effect until the linker 
encounters an RFL block. A library file should be terminated ty an SFL 
block. 



^ TERSE 

Places the editor into TERSE mode. While in TERSE mode, EEB displ^s 
only the first entrypoint name of each module encountered. (See also 
BRIEF and VERIFY. ) 



► TOP 

Moves the pointer to the top of the input file. 

^ VERIFY 

Places EEB into VERIFY mode. All subroutine names and entrypoints, as 
then a^e encountered by EEB, are displayed on the terminal. EEB is 
initialized in the VERIFY mode. (See also BRIEF and lERSE.) 

Obsolete Cotnmands 

The following commands are outmoded but are included for the sake of 
compatibility; 



Writes an end-of-tape mark on the output file ("223, '223 on paper 
tape; word on disk) . Writing an ET to disk causes the linker to 
'ignore tiie ropnainder of the file. 
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^ GENET [G] 

Copies the subroutine to which the pointer is currently positioned and 
follows it with an end-of-tape mark. The pointer moves to the next 
subroutine. The optioial letter G specifies a global copy; all 
subroutines from the current position of the pointer are copied, each 
followed by an end-of-tape mark. When the bottom of the input file is 
encountered, ECB displays .BOTTOM, on the terminal. 



^ OMITET [G] 

Copies the subroutine to which the binary location pointer is currently 
positioned. The pointer moves to the next subroutine. The optional 
letter G specifies a global copy; all subroutines from the current 
position of the pointer are copied. When the bottom of the input file 
is encountered, EDB displays .BCTICM. on the terminal. 



ECB Error Messages 

EDB displays ENTER to show that it is ready to accept commands. Most 
errors in command input cause EEB to display a question mark (?) . 
Other messages are listed below. 



• BAD OBJECT PILE (FREBIN) 

Usually indicates that you have specified a source file, ratiier than an 
object (.BIN) file, as the input file. ECB attempts to continue 
processing by ignoring the ranainder of the input file. 



• BAD PARA^ETERS (ECB) 

Indicates an error while locating an input file, an output file, or a 
replace file; or, indicates an erroneous usage of ECB. EEB 
terminates. 



• ERROR WHILE WRITING 

A file system error occurred while EEB was trying to write the contents 
of an object file. EEB terminates. 
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EXRMFLES 

Creating a Library of Subroutines 

The following exampie creates a library from the files FILEl.BINr 
FILE2.BIN, FILE3.BIN, and FILE4.BIN. Each file contains a single 
module, althou^ FILE1.BIN and FILE2.BIN contain multiple entrypoints. 
The example shews the EDB commands to list the entrypoints of each 
file, pLus the commands necessary to combine them into a library file, 
LIBEXP.BIN. 



OK, ECB FILE1,BIN 

[EEB rev 19.4] 

ENTER, FIND ALL 

ENTIA ENTIB 

ENTLC 

.BOOTOM. 

ENTER, NEWINF FILE2.BIN 

ENTER, FIND ALL 

HS1T2D ENT2E 

.BOTTOM. 

ENTER, NEWINF FILE3.BIN 

ENTER, FIND ALL 

ENT3G 

.BOTTOM. 

ENTER, NESJINF FILE4.BIN 

ENTER, FIND ALL 

ENT4H 

.BOTTOM. 

ENTER, OPEN LIBEXP.BIN 

ENTER, NEWINF FILE1.BIN 

ENTER, RFL 

ENTER, COPY ALL 

ENTIA EOTIB 

ENTIC 

.BOTTOM. 

ENTER, INSERT FILE2.BIN 

ENTER, INSERT FILE3.BIN 

ENTER, INSERT FILE4.BIN 

ENTER, SFL 

ENTER, QUIT 

OK, 



After a library is created, LIBEEB can be run on it to speed its 
linking time. 
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Displaying Entrypoints 

Notice the difference between the terminal output in VERIF5f and TERSE 
modes. ENT5A and ENT6A are both entrypoints of the module in the file 
FILE5.BIN; ENT5A is the name of the procedure, ENT6A is the name of an 
alternate entrypoint to the ENTSA procedure. In TERSE mode, only ENT6A 
is listed, (The compiler in this case emits the external name for the 
alternate entrypoint before it emits the external name for the 
procedure; therefore, ENT6A is listed first.) For example: 



OK, ECB FILE5.BIN 

[EEB rev 19.4] 

ENTER, FIND ALL 

ENT6A ENT5A 

.BOTTOM. 
ENTER, TOP 
ENTER, TERSE 
ENTER, FIND ALL 
ENT6A 
.BOTTOM. 
ENTER, QUIT 
OK, 



Replacing an Object Module in the Library 

The library file created above, LIBEXP.BIN, is edited to replace the 
module containing entry point EMTSG with the module in NFILE3.BIN 
containing entry points ENT3F and E17r3G. The output file is 
LIBNEW.BIN. 



OK, ECB NFILE3.BIN 

[EEB rev 19.4] 

ENTER, FIND ALL 

ENT3P ENT3G 

.BOTDOM. 

ENTER, QUIT 

OK, ECB LIBEXP.BIN LIBNEW.BIN 

[EEB rev 19.4] 

ENTER, REPLaC ENT3G NFILE3.BIN 

<RFL> ENTIA 

ENTIB ENTIC 

ENT2D ENT2E 

ENT3G 

ENTER, COPY ALL 

ENT4H <SFL> 

.BOTTOM. 
ENTER, QUIT 
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OK, EEB LIBNEW.BIN 
[EEB rev 19.4] 
ENTER, FIND ALL 

<RFL> ENTIA 

ENTLB ENTIC 

ENT2D ENT2E 

ENT3F ENT3G 

ENT4H <SFL> 

.BOTTOM. 
ENTER, QUIT 
OK, 



Sample Use of L]BECB 

In this example, the file LIBEXP.BIN is processed by LIBECB, producing 
a SAM file named FAST_J.IBEXP.BIN. 



OK, RESUfC LIB>L]BEIB 
[LIBECB rev 19.0] 

SCDRCE FILE, DESTINATION FILE, ERRAIETER 
WHERE: PARA^ETER = - DESTINATION FILE SAM 

PARAMETER = 2000 - DESTINATION FILE DAM 
$ LIBEXP.BIN, FAST_Ji3BEXP.BIN,0 
OK, 
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A 



Converting Programs 

That Use Register 

Settings 



Sane existing static-mode programs use register settings to select 
options for the program. Register settings set the initial values of 
R-mode arwa V-mode registers for static-mode programs by setting values 
in the BVBC (Register VECtor) for the user. (See the IRIM3S Commands 
Reference Guide for more information on RVEC and register settings. ) 

While using register settings to select program options is obsolete, 
having been replaced by the more legible and flexible craranand line 
options (such as -LISTIN3, -XREF, and so on), register settings do 
offer the advantage of being able to change the default options for a 
program without having to recompile or reload it. 

For example, to change the register settings for a program named NRSL, 
you mi^t type : 



RESTORE NRa.SAVE 
SAVE NRSL. SAVE 3/14520 



This cranmand sequence would change the initial value of the A register 
for NRSL from its original value of 120 to 14520. This mi^t have the 
effect of aiabling more options ty default; users subsequently 
invoking the program would not have to specify those options. 
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Converting such a program to an EPF mi^t seem difficult at first, 
because this feature is not directly supplied ty BIND and EPFs. 
However, a feature exists that is easier to use with BIND and EPFs and 
that may be a suitable replacement. This appendix shows how to use 
this feature to provide a somewhat compatible interface for setting the 
initial values of registers. 

First, the appendix provides a short discussion of hew the present 
static-mode program uses the initial values of registers. Then, using 
that model, the appendix describes how to accomplish the same thing 
using BIND and EPFs. 



HOW THE STATIC-M3DE PROGRAM WORKS 

The key to the use of initial values for registers fcy a static-mode 
progran is that its first instructions that reference the appropriate 
registers must not initialize them before using them, because the 
command processor has alrea<fy initialized them. Their values are 
stored in the first nine hal&rords of the static-mode runfile 
containing the program. The first two of these halJ&»7ords are the 
beginning and ending addresses for the program's memory image; the 
third hal&?ord is the starting location of the program (the initial 
value of the P register) ; and the next four halfwords contain tiie 
initial values for the A, B, X, and K registers. The remaining two 
hal&7ords are undefined and should be 0. 

Therefore, the main entrypoint of a static-mode program that utilizes 
the initial values of one or more registers usually begins with a STA, 
STL, or STX instruction if written in EMA, or with a call to the GETA 
or GETL subroutine if written in FTN. (GETA st cares the value in the A 
register into the INT03ER*2 argument passed to it, while GETL stores 
the value in the L register, which is the A and B registers 
concatenated, into the nnBGERM argument passed to it.) 

Then, the main entrypoint uses the values retrieved from the registers 
as the initial, or default, values for option settings in the program. 
Typically, the program then reads options from the command line, 
recording any options it finds there on top of the initial option 
settings. (Thus, command line options, when specified, override tiie 
initial values.) 

In addition, the user may use register settings on the command line 
(such as RESUME NRSL 3/10120) instead of command line options. The use 
of this obsolete method of specifying program options is guaranteed to 
confuse and bewilder anybo<^ who tries to understand the command file 
written by the user to invoke the program. (Such a user rarely builds 
a CPL program for the purpose.) These register settings, when 
specified on the oomonnand line, override the settings in the RVEC for 
the static-mode program image, and hence replace the initial values for 
the registers. 
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HOW ID ACHIEVE THIS FUNCTIDNRLCTY IN M EPF 

Tb make the default options for an EPF tailarable on a per-syston 
basis, you build a CPL program that replaces the RESUKE/SAVE ooramand 
sequence shown at the beginning of this appendix; in addition, you 
convert your static-mode program ty changing the way it <±itains the 
initial values of the registers. 



The CPL Program 

The CPL program performs the following tasks: 

1. It determines the default options desired by the user, either 
by accepting the baroque register settings used for tiie 
static-mode version of the program or fcy reading ooramand line 
options typed by the user. 

2. It compiles a small PEN subroutine called NGETA or NSEfflL that 
stores the numeric equivalents to the desired default options 
into the passed argument, either an IMrBGBR*2 (N3EIA) or an 
INTBGER*4 (N3ETL) argument. 

3. It invokes BIND and links the EPF using the subcommand LOAD 
program. FUN. 

4. It uses the RELOAD subcommand to relink the N3ETA or NSEQL 
subroutine just compiled into the EPF just linked. 

5. It uses the FILE subcommand to write to disk the new version of 
the EPF with modified default options. 



Converting the Static-mode Program 

You also convert your static-mode program to obtain the initial values 
for the registers b^ calling a subroutine named NSETA or N3EIL, 
depending upon whether the program uses the initial value for the A 
register or for both the A register and the B register. 

Ihen, you write a subroutine named N3ETA or NGEIL in ETN that you link 
with your program. The subroutine sets the passed number to the 
standard default option settings as numbers and returns to the caller. 



The Result 

The result you have is a program EPF that obtains its initial register 
values by calling N3ETA or NGEIL, an internal subroutine that returns 
•standard values for the registers in the argument provided. Ihe rest 
of your program operates as it did before, 
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If someone wishes to tailor your program for their needB, they need 
only invoke the CPL program you have supplied. It (^stains the desired 
default options from tiie user, and compiles a new version of NSEIA or 
NSEHL that supplies the new initial values instead of the standard 
values. The CPL program then relinks the newly compiled NSETIA or VEEIL 
module into the existing EFF, and now that program EPP uses the new 
defaults. 



A Sample Case 

A sample CPL program that performs this conversion, along with the 
corresponding copy of N5ETA and NSdL, follows. 



&args progitree; areg:oct-120 

&if [null %prog%] &then &return 1 smessage Requires program name. 

&if [index %prog% .HIN] "= [calc [length %prog%] - 3] ~ 

&then &s prog i= %prog%,HJN 
&data ed 

SUBROUTINE N3CIA(I) 

INTBGER*2 I 

I=:%areg% 

rehjrn 

END 

FILE NSEIA. FTN 
&end 

f tn ngeta -dyrm -dclvar 

bind -load %prog% -reload ngeta 

delete ngeta.bin 



Ohe oct=120 in the first line sinpLy sets the default value for the 
initial Ar-register setting if the user does not specify it. It should 
be the same value with which you ship the program EPF. 

As you can see from the above sample CPL program, the sample ICEnSLPEN 
modiLLe is quite single: 



SUBPOUTINE NGESAd) 

INrBGER*2 I 

1= rvalue 

BETUBN 

END 



First Edition A-4 



CONVERTING PROGRAMS THAT USE REGISTER SE^mUGS 



Here, value is the standard initial A-register value. The NGE3L.PIN 
module is as follows: 



SUBRDDTINE NGETL(L) 

INTBGER*2 L(2) 

L(l)=:valuel 

L(2)=:value2 

RETURN 

END 

Here, valuel and value2 are the standard initial A-register and 
B-register values, respectively. If your program ejqects an initial 
value for the B register, you should use the copy of N3ETI. shown above 
and modify the CPL program shown earlier accordingly. (For example, it 
diould take two octal arguments, one for the A register and one for tiie 
B register.) 



If the Main Entrypoint Is a HMA Progran 

If the main entrypoint of your program is writtei in EMA, then you must 
change the STA or STL instruction at the beginning to a OUoL N3E TA o r 
CALL N3B1L followed by AP INnLPBG_SETTING, SL (where INnUfflGLSETTING 
was the target of the OTA or OTL instruction) , If fhe program also 
ejqjects an initial value for the X register, add a tiiird octal ar^jment 
to the CPL program and a second argument to NGBIL to pass the X 
register value, and call NGBIL with a second argument from the IMA 
module that stores the value returned in the second argment in the 
destination of the original STX instruction. 

If the PMA program does not start off with OTA, STL, or STX 
instructions, but instead uses instructions that test the registers in 
various ways (such as SAR, SAS, BBQ, CAS, and so on), simply insert the 
call to NGETA or NGEIL in front of the instructions, then code a LDA, 
II3L, or LDX instruction to load the registers with the initial values 
retrieved from N3ETA or N3E1L. 
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addresses, 9-6 

Building shared programs with 
SEIG, 1-8 
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Command level breadth, 5-3 

Common area, 3-10, 8-1 
defining a shared, 8-2 
initialization of, 3-11 
treatment of ty BIND, 3-11, 
3-15 

Common blocks and dynamic link, 
2-4 

CP$ subroutine, 3-16 

CEL functions and program EPFs, 
1-16 



Pimamic link (continued) 
to entry points in H^IMDS, 

3-22 
to entrypoints in Application 

Library, 3-24 
to entrypoints in FRIMDS, 3-26 
to static-mode libraries, 3-28 

Dynamic linking mechanism, 1-3, 
2-1, 3-6, 3-19 
advantages, 2-1 

Eynamic memory, 1-9 
. deallocation of, 3-32 
in EPFs, 3-3 

DYNT, ( See also Dynamic link) 
as a subcommand of BIND, 5-5 



DATA segnent, 3-7, 3-10, 3-19 
access to, 3-16 

Deallocation of (fynamic memory, 
3-32 

Deallocation of library EPFs, 
3-32 

Debugging an EPF, 
BIND command, 1-18 
EBG command, 3-35 
DUMP_STACK command, 1-18 
LIST_EPF command, 1-18 
other useful commands, 1-19 
setting breakpoints, 1-18 
VPSD command, 1-18, 9-6 

Debugging information in EPFs, 
3-3, 3-7 

Displaying common area addresses, 
3-15 

n3VSP_ffrPCK command, 9-9 

Dynamic link, 5-5 

common blocks and, 2-4 
definition of, 2-2 
sample session, 2-4 

■ snapping, 2-3, 3-21 



BCB (entry control block), 1-3 
information contained in, 1-4 

EDB binary editor, 10-2 to 10-6 
error messages, 10-5 
obsolete commands, 10-5 
subcommands , 10-3 

Entry control block (See ECB) 

ENTRY$.SR, 1-3 

ENTRYNATE, 

as a subcommand of BIND, 3-15 

Entrypoint, 2-2 
as a subcomomand of BIND, 6-8 
determining, for library EPFs, 

6-5 
invocation, 3-19 
main, of a program EPF, 5-4, 

5-5 
modifying the search list of, 

6-12, 6-13 
reserved names, 6-5 
subroutine, declaring, 6-8 



First Edition 



X-2 



Index 



Entrypoint search list, 6-12, 
6-13, 6-32 
advanced use of, 6-37 
default, 6-32 
examining, 6-38 

EPF, (See also Library EPF; 

Process-class library EPF; 

Program EPF; Program-class 
library EPF) 
benefits of, 1-9 
cache, 1-18, 3-34 
coding guidelines for, 7-1 
copies of link frame, 3-4 
debugging information, 3-3 
debugging of, 1-18, 3-35 
definition of, 1-2 
dynamic memory, 3-3 
information contained in, 1-18 
invocation by CP$ subroutine, 

3-16 
invocation by EPF$PUN 

subroutine, 3-16 
invocation, forms of, 3-16 
library, 1-3 
life of an, 3-5 to 3-34 
linkage text, 3-2 
mapped, 3-16 
mechanism, 3-1 
multiple invocations of, 3-34 
rew versions, 1-2, 3-30, 3-34 
old versions, 1-2, 3-34 
organization of, 3-2 
procedure code, 3-2 
program, 1-3 
reason for, 1-4 
renoving fran memory, 1-16, 

3-6, 3-30 
restrictions on writing in PHA, 
7-10 to 7-16 

.RPn suffix, 1-2 

.HJN suffix, 1-2 

running a remote, 3-36 

simultaneous use of, 3-35 

stack space, 3-3 

( See also Stack frame) 

static information and, 4-7 

suspending and restarting, 
1-17 

termination of, 3-6, 3-30, 
3-31 

types of, 1-3 

unmapping, 3-34 



EPF (continued) 
writing in hi^-level 

languages, 7-1 
writing in PMA, 7-2 

EPF generation and use, 
phase 1 (compilation or 

assanbly) , 3-7 
phase 10 (removal), 3-33 
phase 2 (linking), 3-7 
phase 3 (invocation), 3-15 
phase 4 (mapping), 3-16 
jiiase 5 (linkage allocation), 

3-16 
phase 6 (linkage 

initialization) , 3-19 
phase 7 (entrypoint 

invocation) , 3-19 
phase 8 (<^namic links 

snapped) , 3-21 
phase 9 (termination) , 3-30 
phases in, 3-6 
stages in, 3-5 

EPF$ALLC subroutine, 3-6, 3-16 

EPF$DEL subroutine, 3-6, 3-33 

EPF$INIT subroutine, 3-6, 3-19 

EPF$INVK subroutine, 3-6, 3-19 

EPFi^'lAP subroutine, 3-6, 3-16 

EPF$RUN subroutine, 3-5, 3-16 

Executable progran format (See 
EPF) 

Expanded listings, 9-13 

External linkage information, 
3-7 



Faulted IP, 1-3, 2-2, 3-11, 
3-19, 3-21, 6-17 
how to avoid sharing, 4-10 
sharing of, 4-9 
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Freeing segnents of Rrmode 
programs, 1-7 



I-mode programs, 1-5 

Imaginary addresses and EPF 
sharing, 1-14 

linpure code, 1-13 
separation of pure code from, 
1-12, 7-2 

IMRJRE segment, 3-7, 3-10, 3-19 
access to, 3-16 

Indirect pointer ( See IP) 

Initialization, 
of variables, 1-19 
shared data, 8-3, 8-4 

Invoking an EPF, 1-3, 3-15, 5-1, 
5-2 
subroutines for, 3-5 

IP (indirect pointer), 1-3, 3-7 
faulted, 1-3, 2-2, 3-11, 3-21, 

6-17 
how to avoid faring faulted, 

4-10 
resolution of at runtime, 3-10 
sharing of faulted, 4-9 
treatment of by BIND, 3-10, 

3-11 



IB ( See Linkage base) 

LIBEEB binary editor, 10-1 

LIBRARY, 
as a subcommand of BIND, 3-11 
external referaices resolved 
byr 3-11 



Library EPF, 1-3, 1-9 
assembling the IMA entrypoint 

file for, 6-10 
building a FMA entrypoint file 

for, 6-8, 6-9 
choosing the ri^t type of, 

6-4, 6-14, 6-15 
coding a subroutine for, 6-^ 
compiling a subroutine for, 

6-4 
deallocation of, 3-32 
definition of, 6-2 
determining class requirements 

of, 6-29 
determining entrypoints of, 

6-4 
installing a library file, 

6-11 
installing the library EPF, 

6-11 
invoking, 1-3 

linking subroutines of, 6-7 
modifying the entrypoint search 

list, 6-12 
process-class, 3-32, 3-33 
program's view of, 6-4 
program-class, 3-32, 3-33 
programmer's view of, 6-2 
restriction on class mixing of, 

6-16 
restriction on use of language 

I/O, 6-17 
steps in building, 6-2, 6-4 to 

6-13 
storage allocation issues, 

6-41 
storing data in linkage area 

of, 6-17 
using DBG on, 6-30, 6-31 
using EDB to generate a library 

file, 6-10 

Library EPF mechaniam, 6-39 

Limits on calling program EPFs, 
5-3 

Link frame, 3-4, 3-5, 3-10 

Linkage, 
area, 3-32 
area, storing data in, 6-17, 

6-18 
base, 3-4 
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Linkage (continued) 
fault, 2-4 

initialization, 3-19, 6-18 
text, 3-7 
text, in EPFs, 3-2 
text, in subroutines, 3-4 

Linking, 
loaders, history of, 1-4 
purpose of, 3-7 
utilities, 1-2 

LISTLEPF command, 9-3 

LISTL3BGIENT command, 9-5 

LOftD, 1-2, 1-4 



H 



M^IN, 
as a subcommand of BIND, 3-15, 
5-5 

as a subcommand of BIND, 9-5 

Mapping an EET", 3-16 

Maps and addresses, 9-1 

Memory, 
allocation of, 1-10, 1-11 
dynamic, 1-9 
static, 1-9 

Multiple invocations of an EPF, 
3-34 



Object file, 3-7 



EB (See Procedure base) 

pa instruction, 3-4, 3-7, 3-19 



FM^, 

restrictions for EPF execution, 

7-10 
writing EPFs in, 7-2 to 7-10 

IROC segment, 3-7, 3-10 
access to, 3-15 

Procedure, 
base, 3-4 
code in EPFs, 3-2 
code in subroutines, 3-4 
frame, 3-4 

main, of a program EPF, 5-4 
management, 3-4 
text, 3-7 

Process-class library EPF, 3-32, 
3-33, 6-41 
choice of, 6-14 
link sequence for, 6-7 
restrictions on use of, 6-14 
using for shared data, 8-5 

Program, 

I-roode, 1-5 
Rr-raode, 1-4, 1-5 
S-mode, 1-5 
static-^node, 1-4 
V-raode, 1-5 

Program EPF, 1-3, 1-9 
arguments to, 1-16, 5-4 
command line preprocessing, 

1-17 
CHi functions, 1-16 
data returned from, 5-3 
data supplied to, 5-3 
definition of, 5-1 
invoking, 1-3, 5-1, 5-2 
invoking program's view of, 

5-2 
limits on calling, 5-3 
main entrypoint of, 5-4, 7-2 
main procedure of, 5-4 
programmer's view of, 5-1 
stacking of, 1-17 
user's view of, 5-2 
writing the main program, 5-4 

Program-class library EPF, 3-32, 
3-33, 6-40 
choice of, 6-14 
link sequence for, 6-7 
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HON instruction, 3-4 

Pure code, 
separation of in^xire code from, 

1-12, 7-2 
faring of, 1-13 



SBG, 1-2, 1-4 
building shared programs, 1-8 
for invoking V- or I-mode 

programs, 1-7 
for ^ared procedure segnents, 

1-8 
generating static-^mode inages, 

1-8 



R mode, 1-^ 

R-mode programs, 1-4, 1-5 
freeing segnents of, 1-7 

Removal of EPFs, 1-16, 3-30 
process-class library, 3-33 
program EPF, 3-33 
progran-class library, 3-33 

Replacing static-mode libraries, 
3-30 

Reserved entrypoint name list, 
6-6 

Reserved entrypoint names, 6-5 
list of, 6-6 

RESQLVELPEFERRED GOMTON, 
as a subcOTBivand of BIND, 3-15 
to display common area address, 
3-15 

.RPn suffix, 1-2 

.HJN suffix, 1-2 

Running a ronote EPF, 3-36 



S mode, 1-5 

SB (See Stack base) 

Search rule, 1-3, 6-12, 6-33 to 
6-36 



Segnnent access, 

to DATA segnents, 3-16 
to IMPURE segnents, 3-16 
to IRCx: segnents, 3-15 

Segnent number, 
for IMHJRE and DATA segnent, 

9-3 
for PURE segnent, 9-3 
in addresses, 9-2 
sign of, 9-2, 9-3 
use of by BIND, 3-10 

Segnents, 
shared system-wide, 1-8, 8-3 
static, 8-3 

Separation of pure and impure 
code, 1-13, 1-15 

Shared applications, (See also 
Shared programs) 
effect of EPFs on existing, 
4-8 

Shared data, 8-1 to 8-7 
determining the address of, 

8-2 
how to update atomically, 8-7, 

8-8 
initializing, 8-3, 8-4 
FVIA subroutines for updating, 

8-9 to 8-11 
process-wide, 8-1 
system-wide, 8-1 
using a process-class Library 

EPF for, 8-5 

Shared programs, 
deleting old versions, 1-16 
installing new versions, 1-8, 

1-16 
using SEG to build, 1-8 

Shared systan-wide segnents, 1-8 
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Sharing faulted IPs, 4-9 
how to avoid, 4-10 

Sharing of pure code, 1-13 

Simultaneous use of an EPP, 3-35 

Snapping dynamic links, 2-3, 
3-21 

Stack base, 3-4 

Stack frame, 3-4 
addresses of in WVSP^SUPCK 

ooiranand, 9-9 
locating procedure, 9-10 

Stack header, 3-4 

Stack space in EPFs, 3-3 

Stack space in subroutines, 3-4 

Stacking program EPFs, 1-17 

Static data, 3-7 

Static information and EPFs, 
command line information, 4-7 
error information, 4-7 

Static memory, 1-9 

Static-mode applications, ( See 
also Static-mode program) 
conversion strategy, 4-1 
relation of EPFs to, 4-1 
restriction on EPF use of, 4-2 
suspending and continuing, 4-2 

Static-mcx3e library, 3-28 
dynamic link to, 3-28 
replacing, 3-30 
restriction on EPF use of, 4-4 

Static-mode program, 1-5 
(See also Static-mode 

applications) 
characteristics of, 1-5 to 1-7 

Subroutine, (See also library 
EPF) 
converting nonreentrant to 
reentrant, 6-21 to 6-25 



Subroutine (continued) 
determining class requirements 

of, 6-15, 6-16 
determining the use of static 

data by, 6-17, 6-18 
linkage text, 3-4 
nonreentrant proces&-class, 

6-20 
optimizing conversion approach 

to, 6-25 to 6-28 
organization of, 3-4 
procedure code, 3-4 
process-class, 6-15 
program-class, 6-15 
stack space, 3-4 
storing data in linkage area 

of, 6-18 

Subroutine libraries, 2-1 
types of, 2-2 

Subroutine not found condition, 
2-4 

Subroutines, 
dynamic linking of, 2-1 

Subroutines for invoking EPFs, 
3-5 

SYMBOL, 
as a subcommand of BIND, 3-11, 

8-2, 8-4 
to locate common areas, 3-11 



Terminating an EPF, 3-6, 3-30, 
3-31 

Types of EPFs, 1-3 
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Urroapping an EPF, 3-34 
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